feat: Prepare the next pluginkit release

pluginkit/CHANGELOG.md

@@ -7,6 +7,13 @@ Releases of this module are tagged `pluginkit/vX.Y.Z`. Releases up to
 
 - The module moved to `github.com/gopherium/framework/pluginkit`.
 - The module needs Go 1.27.1.
+- `Host.Migrate` applies every `Migrator` in order without starting any plugin.
+- `Host.Start` takes a stop grace and refuses one that is not above zero, a breaking change.
+- A failed `Host.Start` stops the started plugins within the stop grace, even after its context ends.
+- The generated wiring registers every plugin it can and returns one error naming each failure.
+- The generated wiring imports the SDK as `sdk`, so an SDK package with another name compiles.
+- `wire.Config` gains an optional `Reserved` list of ids no plugin may take.
+- `wire.Run` refuses a plugin id the generated Go or TypeScript wiring cannot use as an import name.
 
 ## 0.5.0 - 2026-08-14
 

pluginkit/graphwire/CHANGELOG.md

@@ -19,6 +19,10 @@ stdlib-only `pluginkit` module so its gqlparser dependency never enters
 - The module moved to `github.com/gopherium/framework/pluginkit/graphwire`.
 - The module needs Go 1.27.1.
 
+### Fixed
+
+- `Run` refuses a graphql plugin whose Go name collides with a name of the generated wiring.
+
 ## [0.3.0] - 2026-08-14
 
 ### Added

pluginkit/graphwire/generate.go

@@ -77,7 +77,7 @@ type imported struct{ alias, path string }
 func wiringImports(cfg Config, plugins []contributor, n naming) []imported {
 	imports := []imported{{"graph", cfg.ExecImport}}
 	if len(plugins) > 0 {
-		imports = append(imports, imported{goName(pathBase(cfg.CoreImport)), cfg.CoreImport})
+		imports = append(imports, imported{coreImportName(cfg), cfg.CoreImport})
 	}
 	if n.packageMode {
 		imports = append(imports, imported{"sdk", cfg.SDKImport})
@@ -105,14 +105,6 @@ func writeImports(b *strings.Builder, cfg Config, plugins []contributor, n namin
 	b.WriteString(")\n\n")
 }
 
-// pathBase returns the last segment of an import path.
-func pathBase(path string) string {
-	if i := strings.LastIndex(path, "/"); i >= 0 {
-		return path[i+1:]
-	}
-	return path
-}
-
 // writePassthrough renders the zero plugin root.
 func writePassthrough(b *strings.Builder, n naming) {
 	fmt.Fprintf(b, "// %s returns the core resolver root, no plugin extends the graph.\n", n.rootFunc())

pluginkit/graphwire/graphwire.go

@@ -9,7 +9,9 @@ import (
 	"errors"
 	"fmt"
 	"go/format"
+	"go/token"
 	"os"
+	"path"
 	"path/filepath"
 	"regexp"
 	"sort"
@@ -263,21 +265,44 @@ func coreContributor(root string, cfg Config) (contributor, error) {
 		return contributor{}, err
 	}
 	return contributor{
-		alias: goName(filepath.Base(cfg.CoreImport)),
+		alias: coreImportName(cfg),
 		path:  cfg.CoreImport,
 		field: "core",
 		param: "core",
 		types: types,
 	}, nil
 }
 
+// coreImportName returns the Go name the generated wiring imports the core package under.
+func coreImportName(cfg Config) string {
+	return goName(path.Base(cfg.CoreImport))
+}
+
+// reservedNames are the Go names the generated wiring owns, keyed by whether it writes a named package.
+var reservedNames = map[bool]map[string]bool{
+	false: {"core": true, "graph": true, "init": true, "main": true},
+	true:  {"core": true, "graph": true, "init": true, "sdk": true, "errors": true, "error": true, "nil": true},
+}
+
+// refuseCollision rejects a graphql plugin id whose Go name collides with a name of the generated wiring.
+func refuseCollision(cfg Config, id string) error {
+	name := goName(id)
+	if token.IsKeyword(name) || reservedNames[namingFor(cfg).packageMode][name] || name == coreImportName(cfg) {
+		return fmt.Errorf("graphwire: plugin %s: its Go name %s collides with the generated wiring", id, name)
+	}
+	return nil
+}
+
 // pluginContributors scans every graphql flagged plugin into contributor entries.
-func pluginContributors(root string, manifests []manifest) ([]contributor, error) {
+func pluginContributors(root string, cfg Config, manifests []manifest) ([]contributor, error) {
 	var contributors []contributor
 	for _, m := range manifests {
 		if !m.GraphQL {
 			continue
 		}
+		if err := refuseCollision(cfg, m.ID); err != nil {
+			return nil, err
+		}
 		scanned, err := scanPlugin(root, m)
 		if err != nil {
 			return nil, err
@@ -326,7 +351,7 @@ func Run(root string, cfg Config) error {
 	if err != nil {
 		return err
 	}
-	plugins, err := pluginContributors(root, manifests)
+	plugins, err := pluginContributors(root, cfg, manifests)
 	if err != nil {
 		return err
 	}

pluginkit/graphwire/graphwire_test.go

@@ -5,6 +5,7 @@ package graphwire
 import (
 	"os"
 	"path/filepath"
+	"slices"
 	"strings"
 	"testing"
 )
@@ -550,6 +551,134 @@ func TestFlaggedPluginWithoutSchemaFails(t *testing.T) {
 	}
 }
 
+func TestRunRefusesAPluginIDCollidingWithTheWiring(t *testing.T) {
+	t.Parallel()
+
+	modes := []struct {
+		name   string
+		cfg    Config
+		output string
+		ids    []string
+	}{
+		{"main mode", testConfig, filepath.Join("cmd", "myapp"),
+			[]string{"core", "graph", "graphres", "init", "main", "type"}},
+		{"package mode", packageConfig, filepath.Join("internal", "graphroot"),
+			[]string{"core", "graph", "graphres", "init", "sdk", "errors", "error", "nil", "type"}},
+	}
+	for _, mode := range modes {
+		for _, id := range mode.ids {
+			t.Run(mode.name+" "+id, func(t *testing.T) {
+				t.Parallel()
+
+				root := t.TempDir()
+				writeCore(t, root)
+				writePlugin(t, root, id,
+					`{"id": "`+id+`", "name": "Colliding", "backend": "example.com/myapp/plugins/`+id+`", "graphql": true}`,
+					betaSchema)
+				if err := os.MkdirAll(filepath.Join(root, mode.output), 0o755); err != nil {
+					t.Fatalf("creating the output directory: %v", err)
+				}
+				wiring := filepath.Join(root, filepath.FromSlash(mode.cfg.WiringPath))
+				if err := os.WriteFile(wiring, []byte("earlier wiring\n"), 0o644); err != nil {
+					t.Fatalf("writing the earlier wiring: %v", err)
+				}
+
+				err := Run(root, mode.cfg)
+
+				want := "graphwire: plugin " + id + ": its Go name " + id + " collides with the generated wiring"
+				if err == nil || err.Error() != want {
+					t.Errorf("Run() error = %v, want %q", err, want)
+				}
+				if kept, _ := os.ReadFile(wiring); string(kept) != "earlier wiring\n" {
+					t.Errorf("wiring after the refusal = %q, want the earlier file untouched", kept)
+				}
+			})
+		}
+	}
+}
+
+func TestRunAcceptsAnIDOnlyTheOtherModeOwns(t *testing.T) {
+	t.Parallel()
+
+	modes := []struct {
+		name   string
+		cfg    Config
+		output string
+		ids    []string
+	}{
+		{"main mode", testConfig, filepath.Join("cmd", "myapp"), []string{"sdk", "errors", "error", "nil"}},
+		{"package mode", packageConfig, filepath.Join("internal", "graphroot"), []string{"main"}},
+	}
+	for _, mode := range modes {
+		for _, id := range mode.ids {
+			t.Run(mode.name+" "+id, func(t *testing.T) {
+				t.Parallel()
+
+				root := t.TempDir()
+				writeCore(t, root)
+				writePlugin(t, root, id,
+					`{"id": "`+id+`", "name": "Usable", "backend": "example.com/myapp/plugins/`+id+`", "graphql": true}`,
+					betaSchema)
+				if err := os.MkdirAll(filepath.Join(root, mode.output), 0o755); err != nil {
+					t.Fatalf("creating the output directory: %v", err)
+				}
+
+				if err := Run(root, mode.cfg); err != nil {
+					t.Errorf("Run() error = %v, want nil", err)
+				}
+			})
+		}
+	}
+}
+
+func TestRunRefusesAHyphenatedIDWhoseGoNameIsTheCoreImport(t *testing.T) {
+	t.Parallel()
+
+	for _, core := range []string{"example.com/myapp/internal/graph_res", "example.com/myapp/internal/graph-res"} {
+		t.Run(core, func(t *testing.T) {
+			t.Parallel()
+
+			root := t.TempDir()
+			writeCore(t, root)
+			writePlugin(t, root, "graph-res",
+				`{"id": "graph-res", "name": "Colliding", "backend": "example.com/myapp/plugins/graph-res", "graphql": true}`,
+				betaSchema)
+			cfg := packageConfig
+			cfg.CoreImport = core
+
+			err := Run(root, cfg)
+
+			want := "graphwire: plugin graph-res: its Go name graph_res collides with the generated wiring"
+			if err == nil || err.Error() != want {
+				t.Errorf("Run() error = %v, want %q", err, want)
+			}
+		})
+	}
+}
+
+func TestACoreImportWithATrailingSlashKeepsOneName(t *testing.T) {
+	t.Parallel()
+
+	root := t.TempDir()
+	writeCore(t, root)
+	writePlugin(t, root, "graphres",
+		`{"id": "graphres", "name": "Colliding", "backend": "example.com/myapp/plugins/graphres", "graphql": true}`,
+		betaSchema)
+	cfg := packageConfig
+	cfg.CoreImport = "example.com/myapp/internal/graphres/"
+
+	err := Run(root, cfg)
+
+	want := "graphwire: plugin graphres: its Go name graphres collides with the generated wiring"
+	if err == nil || err.Error() != want {
+		t.Errorf("Run() error = %v, want %q", err, want)
+	}
+	imports := wiringImports(cfg, []contributor{{alias: "beta", path: "example.com/myapp/plugins/beta"}}, namingFor(cfg))
+	if !slices.Contains(imports, imported{"graphres", cfg.CoreImport}) {
+		t.Errorf("wiringImports() = %v, want the core imported as graphres", imports)
+	}
+}
+
 func TestGraphQLPluginsRequireABackend(t *testing.T) {
 	t.Parallel()
 

pluginkit/host.go

@@ -7,6 +7,7 @@ import (
 	"errors"
 	"fmt"
 	"net/http"
+	"time"
 )
 
 // Host starts and stops a fixed set of plugins.
@@ -27,9 +28,31 @@ func NewHost(plugins ...Plugin) *Host {
 	return &Host{plugins: plugins}
 }
 
-// Start migrates every [Migrator] plugin, then starts every plugin in registration
-// order, stopping the already-started ones in reverse order when a start fails.
-func (h *Host) Start(ctx context.Context) error {
+// Start migrates and starts every plugin in order, stopping the started ones within stopGrace when one fails.
+func (h *Host) Start(ctx context.Context, stopGrace time.Duration) error {
+	if stopGrace <= 0 {
+		return fmt.Errorf("pluginkit: the stop grace must stand above zero, got %v", stopGrace)
+	}
+	if err := h.Migrate(ctx); err != nil {
+		return err
+	}
+	for i, p := range h.plugins {
+		if err := safeCall(ctx, p.ID(), "start", p.Start); err != nil {
+			return errors.Join(err, h.rollBack(ctx, stopGrace, i-1))
+		}
+	}
+	return nil
+}
+
+// rollBack stops the plugins from index down under a context stopGrace bounds and the end of ctx cannot cancel.
+func (h *Host) rollBack(ctx context.Context, stopGrace time.Duration, index int) error {
+	stopping, cancel := context.WithTimeout(context.WithoutCancel(ctx), stopGrace)
+	defer cancel()
+	return h.stopDownFrom(stopping, index)
+}
+
+// Migrate applies the schema of every [Migrator] plugin in registration order, stopping at the first failure.
+func (h *Host) Migrate(ctx context.Context) error {
 	for _, p := range h.plugins {
 		migrator, ok := p.(Migrator)
 		if !ok {
@@ -39,11 +62,6 @@ func (h *Host) Start(ctx context.Context) error {
 			return err
 		}
 	}
-	for i, p := range h.plugins {
-		if err := safeCall(ctx, p.ID(), "start", p.Start); err != nil {
-			return errors.Join(err, h.stopDownFrom(ctx, i-1))
-		}
-	}
 	return nil
 }