feat: [#959] add WithCommandsFilter builder to scope registered Artisan commands#1500

goravel-coder · 2026-06-20T03:24:00Z

Why

Closes goravel/goravel#959. The framework currently registers every Artisan dev command (about, env:, package:, vendor:publish, make:*, etc.) on every binary, including production server-only builds. There was no supported way to scope this down — ./app --help in production revealed dev commands, and the surface was always the same regardless of environment.

What

Introduces a new WithCommandsFilter(func() []string) builder method on ApplicationBuilder. The callback runs once at Build() time and returns the positive list of command signatures to keep. The list is captured on the Application and applied uniformly to both the framework's defaultCommands batch (foundation/application.go:defaultCommands) and the console/console/* batch registered by console.ServiceProvider.Boot.

Matching rules (signature-only — category is never consulted):

exact match (no wildcard) — checked against command.Signature()
glob match (entry contains *) — checked against command.Signature() via path.Match (* matches any sequence of non-/ characters, ? is a literal character)

Semantics:

Callback returns	Result
method not called	keep every command (default — no migration)
`nil`	keep every command (no filter applied)
`[]string{}`	drop every command
entries	keep only commands whose signature matches

The filter also trims the user-added commands registered via WithCommands(...), so the user cannot bypass the filter by adding commands. The implementation of add first, then filter lives in two places — foundation/application.go:configureCommands filters user-added commands, and console.ServiceProvider.Boot filters its own batch.

User-facing API

return foundation.Setup().
    WithCommandsFilter(func() []string {
        if facades.Config().GetString("app.env") == "production" {
            return []string{
                "up", "down", "key:generate", "about",
                "env:*",     // glob
                "make*",     // glob (matches make, make:controller, make:test, ...)
                "package:*", // glob
                "vendor:publish",
            }
        }
        return nil // dev/staging: keep everything
    }).
    // ...

The user can also drive the list from build tags or ldflags instead of facades.Config() — the framework doesn't care, it just consumes the returned slice.

Files

console/application.go — new FilterCommandsByAllowlist helper (signature-only, *-only glob)
console/service_provider.go — apply filter to the console/console/* batch via the new Application.ConsoleCommandsFilter() getter
foundation/application.go — new consoleCommandsFilter field, Build() capture, defaultCommands and configureCommands apply the filter
foundation/application_builder.go — new WithCommandsFilter method
contracts/foundation/application.go + application_builder.go — interface extensions
mocks/foundation/Application.go + ApplicationBuilder.go — regenerated via go tool mockery
Tests added in console/application_test.go, console/service_provider_test.go (new), foundation/application_test.go, foundation/application_builder_test.go

Breaking changes

None. Default behavior is unchanged for every existing app — WithCommandsFilter is opt-in.

Test plan

go build ./... — clean
go test ./... — all pass (foundation, console, console/console, plus every downstream package that uses mocks/foundation)
go vet ./... — clean
New tests cover: nil/empty/exact/glob/mixed/question-mark-literal/whitespace-only/category-not-matched/up-down-by-signature, the "add first, then filter" composition between WithCommands and WithCommandsFilter, and the nil/[]string{}/entries distinction on both registration paths.

codecov · 2026-06-20T03:27:05Z

Codecov Report

❌ Patch coverage is 84.61538% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 69.57%. Comparing base (d44f2c8) to head (58911c1).

Files with missing lines	Patch %	Lines
foundation/application.go	33.33%	4 Missing ⚠️
console/service_provider.go	50.00%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1500      +/-   ##
==========================================
+ Coverage   69.43%   69.57%   +0.13%     
==========================================
  Files         378      378              
  Lines       29782    29813      +31     
==========================================
+ Hits        20680    20743      +63     
+ Misses       8147     8114      -33     
- Partials      955      956       +1

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

…an commands Introduces a parameter-less WithCommandsFilter callback on ApplicationBuilder that returns the positive list of command signatures to keep when the framework registers its own Artisan commands. The list is captured once at Build() time and applied to both the framework's defaultCommands batch and the console/console/* batch registered by console.ServiceProvider. Matching rules (signature-only, no category matching): - exact match (no wildcard) -> command.Signature() - glob match (entry contains '*') -> command.Signature() via path.Match ('?' is a literal character) Semantics: - method not called -> keep every command (default) - callback returns nil -> keep every command (no filter) - callback returns []string{} -> drop every command - callback returns entries -> keep only matching commands The filter also trims the user-added commands registered via WithCommands, so the user cannot bypass the filter by adding commands. Closes goravel/goravel#959

hwbrzzl · 2026-06-20T03:31:36Z

 	Commands([]console.Command)
+	// ConsoleCommandsFilter returns the captured positive-list of command
+	// signatures to keep (set via WithCommandsFilter). nil means no filter.
+	ConsoleCommandsFilter() []string


Suggested change

ConsoleCommandsFilter() []string

CommandsFilter() []string

Renamed to CommandsFilter() throughout the codebase.

hwbrzzl · 2026-06-20T03:33:06Z

+	app.EXPECT().MakeConfig().Return(configFacade).Maybe()
+	app.EXPECT().MakeProcess().Return(processFacade).Maybe()


Why use Maybe? It should be avoided. The same as below.

Replaced .Maybe() with explicit .Once() in all three Boot test functions.

hwbrzzl · 2026-06-20T03:34:23Z

+	// WithCommandsFilter registers a callback that returns the positive list of
+	// command signatures to keep when the framework registers its own Artisan
+	// commands. The callback runs once at Build() time.
+	//
+	// Each entry in the returned slice is matched in one of two ways:
+	//   - Exact match (no wildcard) — checked against command.Signature().
+	//   - Glob match (the entry contains '*') — checked against
+	//     command.Signature() using stdpath.Match. '*' matches any sequence
+	//     of non-'/' characters. '?' is not a wildcard.
+	//
+	// Category is never consulted. The filter is signature-only.
+	//
+	// Semantics:
+	//   - Method not called           → keep every command (default).
+	//   - Callback returns nil        → keep every command (no filter).
+	//   - Callback returns []string{} → drop every command (filter, no matches).
+	//   - Callback returns entries    → keep only commands whose signature
+	//     matches an entry (exact or glob).
+	//
+	// The filter applies to user-added commands from WithCommands as well,
+	// so the user cannot bypass the filter by adding commands.


Simplify the annotation

Simplified the docstring. Also clarified that only * triggers glob matching and ? is matched literally as an exact match.

hwbrzzl · 2026-06-20T03:35:13Z

+	publishGroups         map[string]map[string]string
+	json                  foundation.Json
+	bootedRunners         []string
+	consoleCommandsFilter []string


Suggested change

consoleCommandsFilter []string

commandsFilter []string

Renamed to commandsFilter.

hwbrzzl · 2026-06-20T03:36:49Z

+// WithCommandsFilter registers a callback that returns the positive list of
+// command signatures to keep when the framework registers its own Artisan
+// commands. The callback runs once at Build() time; the user can call
+// facades.Config() inside it to read app.env or any other setting without
+// needing a parameter.
+//
+// Each entry in the returned slice is matched in one of two ways:
+//
+//   - Exact match (no wildcard) — checked against command.Signature().
+//   - Glob match (the entry contains '*') — checked against
+//     command.Signature() using stdpath.Match. '*' matches any sequence
+//     of non-'/' characters. '?' is not a wildcard.
+//
+// Category is never consulted. The filter is signature-only.
+//
+// Semantics:
+//
+//   - Method not called           → keep every command (default).
+//   - Callback returns nil        → keep every command (no filter).
+//   - Callback returns []string{} → drop every command (filter, no matches).
+//   - Callback returns entries    → keep only commands whose signature
+//     matches an entry (exact or glob).
+//
+// Composition with WithCommands:
+//
+// WithCommands adds extra commands to the framework's set; WithCommandsFilter
+// then trims the combined set. The filter applies to user-added commands
+// too, so the user cannot bypass the filter by adding commands.


Done — simplified in the implementation as well.

hwbrzzl · 2026-06-20T03:41:16Z

+func (s *ApplicationTestSuite) TestDefaultCommandsUpDownBySignature() {
+	s.app.SetJson(foundationjson.New())
+	s.app.Instance(binding.Route, mocksroute.NewRoute(s.T()))
+	s.app.consoleCommandsFilter = []string{"up", "down"}
+
+	commands := s.app.defaultCommands()
+	got := commandSignatures(commands)
+
+	s.Contains(got, "up")
+	s.Contains(got, "down")
+	s.NotContains(got, "about")
+}


This case is unnecessary, duplicated.

Removed the duplicate test.

goravel-coder

Review of PR #1500

Diff: https://critique.work/v/49ae9fcc92287dcc8b95ca92b00f9215

What it does

Adds WithCommandsFilter() to the ApplicationBuilder, allowing users to scope which built-in Artisan commands get registered -- particularly useful for production-only binaries that don't need make:*, package:*, vendor:publish, etc.

What's good

Comprehensive tests -- table-driven tests cover nil/empty/whitespace/glob/exact/literal-? cases across both unit (FilterCommandsByAllowlist) and integration-level (defaultCommands, configureCommands, service provider) tests. All pass green.
Go vet clean -- no issues.
Defensive nil check -- registerCommands now checks artisanFacade == nil before proceeding.
Clean API -- WithCommandsFilter(func() []string) is a typical builder pattern, callback delayed to Build() so it can read config/env.
Consistent semantics -- nil allowlist = keep all, []string{} = drop all, entries = keep only matches. Documented in both contract and implementation.
Filter applies everywhere -- console SP commands, defaultCommands(), and user WithCommands() commands all go through the same gate.

Issues

Medium: Docstring misleads about `path.Match` semantics

The docstring claims '?' is not a wildcard, which is technically true for this implementation (only * triggers the glob path), but the docstring also says matching uses stdpath.Match -- which does treat ? as a wildcard. A user reading the docs might think ? behaves like path.Match's ?, but it doesn't because the code only routes patterns containing * to path.Match. Patterns with ? but no * go to exact match.

Suggestion: Clarify in the docstring that the glob path is only triggered by * presence, and patterns without * are exact-matched regardless of ? content.

Low: Double Boot of service providers

Boot() (line 92) and Build() (line 106) both call r.providerRepository.Boot(r). This means if a goravel app calls both Boot() and then Build(), console SP's registerCommands runs twice (once without filter, once with filter). This is pre-existing and not introduced by this PR, but worth noting since the filter now adds a behavioral difference between the two calls.

Low: `TestServiceProviderBootNilAllowlistRegistersAll` uses `.Maybe()` for config/process

The test at console/service_provider_test.go:57 asserts the console SP registers exactly 4 commands when filter is nil. This is correct, but the test doesn't verify that MakeConfig() and MakeProcess() are actually called -- they use .Maybe() which can match 0 times. This is fine for testing filtering but could mask regressions if the underlying command constructors change their dependencies.

Verdict

Request changes -- The docstring clarification about ? behavior is the main ask. The code and tests themselves are solid.

- Rename ConsoleCommandsFilter() -> CommandsFilter() (contract, impl, tests, mocks) - Rename consoleCommandsFilter -> commandsFilter (field name) - Simplify WithCommandsFilter docstrings and clarify ? behavior - Replace .Maybe() with explicit .Once() in service provider tests - Remove duplicate TestDefaultCommandsUpDownBySignature test - Add comment on console.Application.Register clarifying filtering is caller's responsibility

hwbrzzl · 2026-06-20T04:12:18Z

 	commands                   func() []console.Command
 	config                     func()
 	configuredServiceProviders func() []foundation.ServiceProvider
+	commandsFilter      func() []string


The lint is incorrect.

Move FilterCommandsByAllowlist into registerCommands() so ALL callers (defaultCommands, configureCommands, Commands()) go through the same gate. Remove redundant filtering from defaultCommands() and simplify configureCommands() to use registerCommands(). Update tests to verify filtering through the Commands() path.

goravel-coder requested a review from a team as a code owner June 20, 2026 03:24

goravel-coder force-pushed the feat/optional-artisan-bundle branch from 6161684 to ede0de0 Compare June 20, 2026 03:29

hwbrzzl reviewed Jun 20, 2026

View reviewed changes

goravel-coder commented Jun 20, 2026

View reviewed changes

hwbrzzl reviewed Jun 20, 2026

View reviewed changes

hwbrzzl added 2 commits June 20, 2026 12:13

optimize

58911c1

hwbrzzl merged commit 2059fd0 into master Jun 20, 2026
17 of 19 checks passed

hwbrzzl deleted the feat/optional-artisan-bundle branch June 20, 2026 05:38

This was referenced Jun 20, 2026

feat: add WithCommandsFilter example (#126) goravel/example#126

Merged

fix: SIGSEGV on artisan migrate when database connection is unavailable #1501

Closed

		app.EXPECT().MakeConfig().Return(configFacade).Maybe()
		app.EXPECT().MakeProcess().Return(processFacade).Maybe()

Uh oh!

Conversation

goravel-coder commented Jun 20, 2026

Why

What

User-facing API

Files

Breaking changes

Test plan

Uh oh!

codecov Bot commented Jun 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

goravel-coder left a comment

Choose a reason for hiding this comment

Review of PR #1500

What it does

What's good

Issues

Medium: Docstring misleads about path.Match semantics

Low: Double Boot of service providers

Low: TestServiceProviderBootNilAllowlistRegistersAll uses .Maybe() for config/process

Verdict

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

codecov Bot commented Jun 20, 2026 •

edited

Loading

Medium: Docstring misleads about `path.Match` semantics

Low: `TestServiceProviderBootNilAllowlistRegistersAll` uses `.Maybe()` for config/process