feat: release v0.28 generic Go project scaffolding and lifecycle entry

examples/program/internal/config/config.go

@@ -0,0 +1,29 @@
+package config
+
+import (
+	omniConfig "git.yuntuo.hk/k2safe/go-omni/config"
+	"git.yuntuo.hk/k2safe/go-omni/lifecycle"
+	"git.yuntuo.hk/k2safe/go-omni/logx"
+)
+
+// Config, Default and Validate are project-owned. Add project settings here.
+type Config struct {
+	Once      bool                     `json:"once"`
+	Log       logx.Config              `json:"log"`
+	Lifecycle lifecycle.ShutdownConfig `json:"lifecycle"`
+}
+
+func Default() Config {
+	log := logx.Default()
+	log.Service = "example.com/program"
+	return Config{Once: true, Log: log, Lifecycle: lifecycle.DefaultShutdownConfig()}
+}
+func (c Config) Validate() error {
+	if err := c.Log.Validate(); err != nil {
+		return omniConfig.AtField("log", err)
+	}
+	if err := c.Lifecycle.Validate(); err != nil {
+		return omniConfig.AtField("lifecycle", err)
+	}
+	return nil
+}

examples/program/internal/config/loadGen.go

@@ -0,0 +1,12 @@
+// Code generated by go-omni project. DO NOT EDIT.
+package config
+
+import omniConfig "git.yuntuo.hk/k2safe/go-omni/config"
+
+func Load(path string) (Config, error) {
+	loader, err := NewLoader()
+	if err != nil {
+		return Config{}, err
+	}
+	return omniConfig.LoadProject(path, Default(), loader)
+}

examples/program/internal/config/loader.go

@@ -0,0 +1,6 @@
+package config
+
+import omniConfig "git.yuntuo.hk/k2safe/go-omni/config"
+
+// NewLoader is project-owned. Register additional decoders here if needed.
+func NewLoader() (*omniConfig.Loader, error) { return omniConfig.NewLoader() }

examples/program/internal/run/run.go

@@ -0,0 +1,19 @@
+package run
+
+import (
+	"context"
+	"example.com/program/internal/svc"
+)
+
+// Run is project-owned. Return nil for normal completion, or an error to fail.
+// The starter waits for shutdown; a one-shot program can simply return when done.
+// Register background stop/drain hooks in svc.Init, not concurrently here.
+// Accepted background work uses deps.WorkContext(), not the early-stop ctx.
+func Run(ctx context.Context, deps *svc.ServiceContext) error {
+	if deps.Config.Once {
+		deps.Logger.InfoContext(ctx, "program.completed")
+		return nil
+	}
+	<-ctx.Done()
+	return nil
+}

examples/program/internal/svc/runtimeGen.go

@@ -0,0 +1,44 @@
+// Code generated by go-omni project. DO NOT EDIT.
+package svc
+
+import (
+	"context"
+	"errors"
+	"example.com/program/internal/config"
+	"fmt"
+	"git.yuntuo.hk/k2safe/go-omni/lifecycle"
+	"git.yuntuo.hk/k2safe/go-omni/logx"
+)
+
+func New(ctx context.Context, logger *logx.Logger, cfg config.Config) (result *ServiceContext, err error) {
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	if err = ctx.Err(); err != nil {
+		return nil, errors.Join(err, lifecycle.Cause(ctx))
+	}
+	if logger == nil {
+		return nil, errors.New("service context requires a logger")
+	}
+	if err = cfg.Validate(); err != nil {
+		return nil, err
+	}
+	runtime, err := lifecycle.NewRuntimeWithConfig(logx.WithLogger(ctx, logger), cfg.Lifecycle)
+	if err != nil {
+		return nil, err
+	}
+	c := &ServiceContext{Runtime: runtime, Config: cfg, Logger: logger}
+	defer func() {
+		if p := recover(); p != nil {
+			err = fmt.Errorf("dependency initialization panic: %v", p)
+		}
+		if err != nil {
+			result = nil
+			err = c.Finish(err)
+		}
+	}()
+	if err = c.Init(c.Context()); err != nil {
+		return nil, err
+	}
+	return c, nil
+}

examples/program/internal/svc/serviceContext.go

@@ -0,0 +1,24 @@
+package svc
+
+import (
+	"context"
+	"example.com/program/internal/config"
+	"git.yuntuo.hk/k2safe/go-omni/lifecycle"
+	"git.yuntuo.hk/k2safe/go-omni/logx"
+)
+
+// ServiceContext is project-owned. Add dependencies without global variables.
+// Runtime owns registered resources; Logger is borrowed from the entry point.
+type ServiceContext struct {
+	*lifecycle.Runtime
+	Config config.Config
+	Logger *logx.Logger
+}
+
+// Init runs before Run. Register resources immediately with OnClose.
+// Register paired OnStop/OnDrain hooks before exposing background work.
+// Use WorkContext for accepted work; Context is the early stop notification.
+// OnDrain returns nil only after processing and final cleanup have completed.
+// Complete all registrations here, before Run can race with shutdown.
+// The drain name "go-omni/project/run" is reserved for the generated entry.
+func (c *ServiceContext) Init(ctx context.Context) error { return nil }