feat: adopt shared plugin authoring APIs

Author: AntoineToussaint

agent.codefly.yaml

@@ -1,3 +1,3 @@
 publisher: codefly.dev
 name: python
-version: 0.0.7
+version: 0.0.8

go.mod

@@ -5,7 +5,7 @@ go 1.25.0
 toolchain go1.26.4
 
 require (
-	github.com/codefly-dev/core v0.2.11
+	github.com/codefly-dev/core v0.2.16
 	gopkg.in/yaml.v3 v3.0.1
 )
 

go.sum

@@ -33,6 +33,8 @@ github.com/clipperhouse/uax29/v2 v2.7.0 h1:+gs4oBZ2gPfVrKPthwbMzWZDaAFPGYK72F0NJ
 github.com/clipperhouse/uax29/v2 v2.7.0/go.mod h1:EFJ2TJMRUaplDxHKj1qAEhCtQPW2tJSwu5BF98AuoVM=
 github.com/cloudflare/circl v1.6.3 h1:9GPOhQGF9MCYUeXyMYlqTR6a5gTrgR/fBLXvUgtVcg8=
 github.com/cloudflare/circl v1.6.3/go.mod h1:2eXP6Qfat4O/Yhh8BznvKnJ+uzEoTQ6jVKJRn81BiS4=
+github.com/codefly-dev/core v0.2.16 h1:94gqpcizi64wSevD1ETk/G1nRSAVawlwYuW7AGFj2ak=
+github.com/codefly-dev/core v0.2.16/go.mod h1:78gNY4qIlPnj08Fe8X5WwXWtqjTvU4MelJlOYTJq/5s=
 github.com/codefly-dev/gortk v0.2.0 h1:7bOlS5valYz2zil+fZctQNcPCYBcPj86abcw9N8h1hQ=
 github.com/codefly-dev/gortk v0.2.0/go.mod h1:dDWUMFgAP063OCGhTEpV7FFUj9+zTcxxO/nV80VKEwg=
 github.com/cyphar/filepath-securejoin v0.6.1 h1:5CeZ1jPXEiYt3+Z6zqprSAgSWiggmpVyciv8syjIpVE=

pkg/builder/builder.go

@@ -1,6 +1,6 @@
 // Package builder implements the generic Python Builder gRPC service.
-// Its job on the generic layer is minimal: Load/Init plumbing, a no-op
-// Build (uv sync happens at Runtime.Init), a no-op Sync (no protos).
+// Its job on the generic layer is minimal: Load/Init plumbing and Configure.
+// Shared successful no-op phases come from services.DefaultBuilder.
 // Specializations override Build (to produce container images) and Sync
 // (to generate protos / adapters / migrations).
 package builder
@@ -20,34 +20,25 @@ import (
 // Builder is the generic Python builder server. Embedded by specializations
 // so they inherit Load/Init and only add what their layer needs.
 type Builder struct {
-	services.BuilderServer
+	*services.DefaultBuilder
 	*pythonservice.Service
 }
 
 // New builds a generic Python Builder bound to the shared Service.
 func New(svc *pythonservice.Service) *Builder {
-	return &Builder{Service: svc}
+	return &Builder{
+		DefaultBuilder: services.NewDefaultBuilder(svc.Builder),
+		Service:        svc,
+	}
 }
 
 // Load reads the identity and settings. Specializations override to wire
 // endpoints and compute layer-specific paths, but should call this first.
 func (s *Builder) Load(ctx context.Context, req *builderv0.LoadRequest) (*builderv0.LoadResponse, error) {
 	defer s.Wool.Catch()
-	ctx = s.Wool.Inject(ctx)
-
-	if err := s.Builder.Load(ctx, req.Identity, s.Service.Settings); err != nil {
-		return s.Builder.LoadError(err)
-	}
-
+	response, err := s.Builder.LoadService(ctx, req, services.BuilderLoad{Settings: s.Service.Settings})
 	s.Service.SourceLocation = s.Location
-
-	if req.CreationMode != nil {
-		s.Builder.CreationMode = req.CreationMode
-		return s.Builder.LoadResponse()
-	}
-
-	s.Endpoints, _ = s.Base.Service.LoadEndpoints(ctx)
-	return s.Builder.LoadResponse()
+	return response, err
 }
 
 // Init records dependency endpoints.
@@ -59,46 +50,21 @@ func (s *Builder) Init(ctx context.Context, req *builderv0.InitRequest) (*builde
 	return s.Builder.InitResponse()
 }
 
-// Update is a no-op on the generic layer.
-func (s *Builder) Update(ctx context.Context, _ *builderv0.UpdateRequest) (*builderv0.UpdateResponse, error) {
-	defer s.Wool.Catch()
-	ctx = s.Wool.Inject(ctx)
-	return &builderv0.UpdateResponse{}, nil
-}
-
-// Sync is a no-op on the generic layer — Python has no protos to generate.
-// Specializations (python-fastapi, python-grpc) override to regenerate
-// their protocol artifacts.
-func (s *Builder) Sync(ctx context.Context, _ *builderv0.SyncRequest) (*builderv0.SyncResponse, error) {
-	defer s.Wool.Catch()
-	ctx = s.Wool.Inject(ctx)
-	return s.Builder.SyncResponse()
-}
-
-// Build is a no-op on the generic layer — uv sync at Runtime.Init handles
-// Python dep resolution; there's no artifact to produce. Specializations
-// override to build container images.
-func (s *Builder) Build(ctx context.Context, _ *builderv0.BuildRequest) (*builderv0.BuildResponse, error) {
-	defer s.Wool.Catch()
-	ctx = s.Wool.Inject(ctx)
-	return s.Builder.BuildResponse()
-}
-
-// Deploy is a no-op on the generic layer. Specializations override to
-// render k8s manifests or push images.
+// Deploy fails explicitly on the generic layer. Returning a success response
+// without producing a workload made the CLI report a deployment that did not
+// exist. Deployable specializations override this method.
 func (s *Builder) Deploy(ctx context.Context, _ *builderv0.DeploymentRequest) (*builderv0.DeploymentResponse, error) {
 	defer s.Wool.Catch()
 	ctx = s.Wool.Inject(ctx)
-	return s.Builder.DeployResponse()
+	return s.Builder.DeployError(fmt.Errorf("generic Python services do not define a deployable workload; use a deployable specialization such as python-fastapi"))
 }
 
-// Create is a no-op on the generic layer. A generic "python service" has
-// no inherent template — it's an abstract starting point. Specializations
-// ship their own templates/factory/ tree and override Create to apply it.
+// Create likewise fails explicitly because the generic layer has no project
+// template. Specializations provide their own factory tree.
 func (s *Builder) Create(ctx context.Context, _ *builderv0.CreateRequest) (*builderv0.CreateResponse, error) {
 	defer s.Wool.Catch()
 	ctx = s.Wool.Inject(ctx)
-	return s.Builder.CreateResponse(ctx, s.Service.Settings)
+	return s.Builder.CreateError(fmt.Errorf("generic Python services do not define a project template; use a concrete specialization"))
 }
 
 // Configure applies structured config changes to the service's test formula and

pkg/builder/builder_test.go

@@ -1,8 +1,11 @@
 package builder_test
 
 import (
+	"context"
+	"strings"
 	"testing"
 
+	builderv0 "github.com/codefly-dev/core/generated/go/codefly/services/builder/v0"
 	"github.com/codefly-dev/core/resources"
 
 	pythonbuilder "github.com/codefly-dev/service-python/pkg/builder"
@@ -24,3 +27,24 @@ func TestBuilderEmbedsService(t *testing.T) {
 	_ = b.Base
 	_ = b.Builder
 }
+
+func TestGenericBuilderRejectsUnsupportedCreateAndDeploy(t *testing.T) {
+	svc := pythonservice.New(&resources.Agent{Kind: "codefly:service", Name: "python"})
+	b := pythonbuilder.New(svc)
+
+	created, err := b.Create(context.Background(), &builderv0.CreateRequest{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if created.GetState().GetState() != builderv0.CreateStatus_ERROR || !strings.Contains(created.GetState().GetMessage(), "concrete specialization") {
+		t.Fatalf("unexpected create response: %+v", created)
+	}
+
+	deployed, err := b.Deploy(context.Background(), &builderv0.DeploymentRequest{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if deployed.GetState().GetState() != builderv0.DeploymentStatus_ERROR || !strings.Contains(deployed.GetState().GetMessage(), "python-fastapi") {
+		t.Fatalf("unexpected deploy response: %+v", deployed)
+	}
+}

pkg/runtime/runtime.go

@@ -33,7 +33,7 @@ import (
 // calling RegisterReplCommands once from their own Load — same pattern
 // go-grpc uses for its explicit registerCommands call.
 type Runtime struct {
-	services.RuntimeServer
+	*services.DefaultRuntime
 	*pythonservice.Service
 
 	// Persistent Python REPL — started lazily on first `exec` command,
@@ -45,7 +45,10 @@ type Runtime struct {
 
 // New builds a generic Python Runtime bound to the shared Service.
 func New(svc *pythonservice.Service) *Runtime {
-	return &Runtime{Service: svc}
+	return &Runtime{
+		DefaultRuntime: services.NewDefaultRuntime(svc.Runtime),
+		Service:        svc,
+	}
 }
 
 // Load reads the agent identity, stores environment, and resolves the
@@ -54,23 +57,18 @@ func New(svc *pythonservice.Service) *Runtime {
 func (s *Runtime) Load(ctx context.Context, req *runtimev0.LoadRequest) (*runtimev0.LoadResponse, error) {
 	defer s.Wool.Catch()
 
-	if err := s.Base.Load(ctx, req.Identity, s.Service.Settings); err != nil {
-		return s.Runtime.LoadErrorf(err, "loading base")
-	}
-
-	s.Runtime.SetEnvironment(req.Environment)
+	response, err := s.Runtime.LoadService(ctx, req, services.RuntimeLoad{Settings: s.Service.Settings})
 
 	// Python convention: source is the service directory itself.
 	s.Service.SourceLocation = s.Location
 	if wd := os.Getenv("CODEFLY_AGENT_WORKDIR"); wd != "" {
 		s.Service.SourceLocation = wd
 	}
 
-	resp, err := s.Runtime.LoadResponse()
-	if resp != nil && resp.Status != nil {
-		resp.Status.Message = pythonhelpers.AppendRuntimeEvidence(resp.Status.Message, pythonhelpers.RuntimeEvidence(s.Service.SourceLocation))
+	if response != nil && response.Status != nil {
+		response.Status.Message = pythonhelpers.AppendRuntimeEvidence(response.Status.Message, pythonhelpers.RuntimeEvidence(s.Service.SourceLocation))
 	}
-	return resp, err
+	return response, err
 }
 
 // Init runs `uv sync` to materialize the venv. Non-fatal on failure.
@@ -229,10 +227,6 @@ func (s *Runtime) Build(_ context.Context, _ *runtimev0.BuildRequest) (*runtimev
 	return &runtimev0.BuildResponse{}, nil
 }
 
-func (s *Runtime) Information(ctx context.Context, req *runtimev0.InformationRequest) (*runtimev0.InformationResponse, error) {
-	return s.Runtime.InformationResponse(ctx, req)
-}
-
 // resolveTestFormula picks the test formula to run: a per-call
 // TestRequest.formula wins, else the service's language-agnostic config formula
 // (resources.Service.Test), else the formula DERIVED from the project, else none