major refactor. core/service/gateway layers

Author: jpnt

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2024 João Pinto
+Copyright (c) 2024-2025 João Pinto
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,62 +1,76 @@
 # kman (Linux Kernel Manager)
 
-kman aims to automate the Linux Kernel installation from source process, allowing for a
+kman aims to automate and unify the Linux Kernel installation from source process, allowing for a
 repeatable way of installing a Linux kernel, generating a initramfs image and updating
-the bootloader configuration, based on the tools and configurations available of your system.
+the bootloader configuration, based on the tools and configurations available of your system,
+offering a sane and powerful way to manage kernels on any Linux distribution.
 
 ## Features
 
-- [x] No External Library dependencies
-- [x] Automated download of Kernel versions
-- [x] Cross-distro compatibility
-- [ ] Configuration file
-- [ ] Incremental updates via patching
-- [ ] Support multiple bootloaders configuration
+
+- [x] Minimal external libraries
+- [x] Cross‑distro compatibility
+- [x] Automated download and verification of kernel versions
+- [ ] Accelerated & cached downloads, incremental updates
+- [ ] Embedded tar.gz/tar.xz multi-threaded decompression
+- [ ] Embedded key signature verification
+- [ ] Ephemeral container build environments
+- [ ] Configuration file support
+- [ ] Support for multiple bootloaders
     - [ ] GNU grub
     - [ ] systemd-boot
     - [ ] limine
     - [ ] rEFInd
-- [ ] Support multiple initramfs generators
+- [ ] Support for multiple initramfs generators
     - [ ] dracut
     - [ ] mkinitcpio
     - [ ] initramfs-tools
     - [ ] booster
-- [ ] distcc support for distributed compilation
-- [ ] modprobed-db support to reduce compile time
-- [ ] Unified kernel image
-
-## Phases
-
-Phases follow this order, all of them are optional and 
-defined either with command flags or with a configuration file.
-
-TODO: ensure all of this phases are correct and in right order
-
-- Linux
-	- list
-	- download
-	- verify
-	- extract
-	- configure
-	- patch
-	- compile
-	- install
-- Initramfs
-	- generate
-- Bootloader
-	- configure
-
-### Design Patterns
-
-It is adopted some level of project maintainability by using some
-of the following design patterns:
-
-- Strategy Pattern: The strategy lets the algorithm vary independently from clients
-  that use it. Used for handling multiple bootloaders (e.g., GRUB, LILO, systemd-boot)
-  and multiple initramfs tools (e.g., Dracut, mkinitcpio, booster) depending on the system.
-- Pipeline Pattern: Encapsulates each step (downloading, configuring, etc)
-  into a set of steps (pipeline), allowing for easy execution and management. Ensures commands
-  are ran in the correct order.
-- Builder Pattern: Provides a flexible way to construct and add kernel configuration parameters
-  step-by-step.
-- Facade Pattern: Manages the kernel context and encapsulates the flow of commands into one component.
+- [ ] distcc, ccache, modprobed-db, and unified kernel image support
+
+## Pipeline Steps
+
+Each step in the pipeline can be executed indidually, but requires some parameter/s.
+
+- Download (url)
+- Verify (archive)
+- Extract (archive)
+- Patch (optional: directory)
+- Configure (optional: .config file, directory, njobs)
+- Compile (optional: directory)
+- Install (optional: directory)
+- Initramfs (optional: initramfs)
+- Bootloader (optional: bootloader)
+
+### Architecture
+
+Some level of software architecture is adopted to make the project maintainability and evolution easier, such
+as separation of concerns (e.g. validation of data separated from execution of code) and responsabilities
+by layer (gateway, service, core); the use of design patterns for step dependency resolution
+and interaction with multiple kinds of outside tools.
+
+As a rule of thumb I like to keep my '.go' files as small as possible, have a component 
+based design and have as little external dependencies as possible, even in outside layers.
+
+The final program must work as a unified cohesive experience.
+
+#### Layers
+
+- Gateway: UI (CLI/TUI/GUI), I/O, Interaction with 3rd party programs.
+- Service: Execution layer, use cases, orchestration logic.
+- Core: Definition of entities, validation, data structures; Does not depend on anything.
+
+Ideally dependencies should flow inward, in practice this is achieved by extensive use of interfaces.
+Interfaces add overhead and they are not always needed. Usually I will have injection of raw implementation
+(without interface) because of that.
+
+#### Design Patterns
+
+- Strategy Pattern: Used to handle multiple bootloader and initramfs tools. The Service layer
+  chooses the right strategy at runtime based on system capabilities and configuration.
+- Pipeline Pattern: Each step (list, download, compile, etc.) is encapsulated as a modular
+  component. The Pipeline Manager in the Service layer coordinates step dependencies and execution order.
+- Builder Pattern: A flexible way to assemble the kernel build configuration step-by‑step,
+  culminating in a unified kernel build process.
+- Facade Pattern: Provides a simplified interface (a unified kernel context) to coordinate the
+  flow of commands across multiple steps.

cmd/kman/kman.go

@@ -3,30 +3,26 @@ package main
 import (
 	"os"
 
-	"github.com/jpnt/kman/internal/kernel"
+	"github.com/jpnt/kman/internal/core"
+	"github.com/jpnt/kman/internal/service"
 	"github.com/jpnt/kman/pkg/logger"
 )
 
 func main() {
 	l := logger.NewLogger(logger.InfoLevel)
-	b := kernel.NewKernelBuilder(l)
 
-	// fmt.Println(args.len())
+	ctx := core.NewKernelContext()
+	p := core.NewPipeline(ctx)
+	f := service.NewStepFactory()
 
-	// TODO: dynamic argument builder configuration
-	// if args.len()
-	b = b.WithDefault()
-	// else:
-	// b = b.WithArguments(args)
+	b := core.NewPipelineBuilder(l, p, f)
 
+	b = b.WithDefault()
+	// TODO: dynamic argument builder configuration
 
-	f, err := b.Build()
+	err := p.Run()
 	if err != nil {
 		l.Error("Error: %s", err.Error())
-	}
-
-	if f.Run() != nil {
-		l.Error("Error: %s", err.Error())
 		os.Exit(1)
 	}
 }

internal/core/context.go

@@ -0,0 +1,46 @@
+package core
+
+import (
+	"errors"
+)
+
+type IKernelContext interface {
+	Validate(stepName string) error
+}
+
+type KernelContext struct {
+	TarballURL    string
+	DownloadPath  string
+	ArchivePath   string
+	Directory     string
+	SignatureURL  string
+	ConfigOptions []string
+	OldConfigPath string
+	NumJobs       string
+	Initramfs     string
+	Bootloader    string
+}
+
+var _ IKernelContext = (*KernelContext)(nil)
+
+func NewKernelContext() IKernelContext {
+	return &KernelContext{}
+}
+
+func (c *KernelContext) Validate(stepName string) error {
+	switch stepName {
+	case "download":
+		if c.TarballURL == "" {
+			return errors.New("kernel tarball URL not set")
+		}
+	case "verify":
+		if c.ArchivePath == "" {
+			return errors.New("kernel archive path not set")
+		}
+	case "extract":
+		if c.ArchivePath == "" {
+			return errors.New("kernel archive path not set")
+		}
+	}
+	return nil
+}

internal/core/pipeline.go

@@ -0,0 +1,53 @@
+package core
+
+import (
+	"fmt"
+)
+
+type IPipeline interface {
+	AddStep(step IStep)
+	Steps() []IStep
+	Ctx() IKernelContext
+	Run() error
+}
+
+type Pipeline struct {
+	steps []IStep
+	ctx   IKernelContext
+}
+
+// Ensure struct implements interface
+var _ IPipeline = (*Pipeline)(nil)
+
+func NewPipeline(c IKernelContext) *Pipeline {
+	return &Pipeline{ctx: c}
+}
+
+func (pl *Pipeline) AddStep(step IStep) {
+	pl.steps = append(pl.steps, step)
+}
+
+func (pl *Pipeline) Steps() []IStep {
+	return pl.steps
+}
+
+func (pl *Pipeline) Ctx() IKernelContext {
+	return pl.ctx
+}
+
+func (pl *Pipeline) Run() error {
+	if len(pl.Steps()) == 0 {
+		return fmt.Errorf("no steps were configured")
+	}
+
+	for _, step := range pl.steps {
+		if err := pl.ctx.Validate(step.Name()); err != nil {
+			return fmt.Errorf("validation failed for step %q: %w", step.Name(), err)
+		}
+
+		if err := step.Execute(); err != nil {
+			return fmt.Errorf("execution failed for step %q: %w", step.Name(), err)
+		}
+	}
+	return nil
+}

internal/core/pipeline_builder.go

@@ -0,0 +1,47 @@
+package core
+
+import (
+	"github.com/jpnt/kman/pkg/logger"
+)
+
+type IPipelineBuilder interface {
+	WithStep(stepName string) IPipelineBuilder
+	WithDefault() IPipelineBuilder
+}
+
+type PipelineBuilder struct {
+	logger  logger.ILogger
+	pl      IPipeline
+	factory IStepFactory
+}
+
+// Ensure struct implements interface
+var _ IPipelineBuilder = (*PipelineBuilder)(nil)
+
+func NewPipelineBuilder(l logger.ILogger, p IPipeline, f IStepFactory) IPipelineBuilder {
+	return &PipelineBuilder{logger: l, pl: p, factory: f}
+}
+
+func (b *PipelineBuilder) WithStep(stepName string) IPipelineBuilder {
+	step, err := b.factory.CreateStep(stepName, b.logger, b.pl.Ctx())
+	if err != nil {
+		b.logger.Warn("Unrecognized step: %q", stepName)
+		return b
+	}
+	b.pl.AddStep(step)
+	return b
+}
+
+func (b *PipelineBuilder) WithDefault() IPipelineBuilder {
+	return b.
+		WithStep("list").
+		WithStep("download").
+		WithStep("verify").
+		WithStep("extract").
+		WithStep("patch").
+		WithStep("configure").
+		WithStep("compile").
+		WithStep("install").
+		WithStep("initramfs").
+		WithStep("bootloader")
+}

internal/core/step.go

@@ -0,0 +1,8 @@
+package core
+
+type IStep interface {
+	Name() string
+	// CtxParamsNeeded() []string // TODO: simpler way?
+	Execute() error
+	// Completed() bool
+}

internal/core/step_factory.go

@@ -0,0 +1,9 @@
+package core
+
+import (
+	"github.com/jpnt/kman/pkg/logger"
+)
+
+type IStepFactory interface {
+	CreateStep(name string, logger logger.ILogger, ctx IKernelContext) (IStep, error)
+}