Refactor/dead code and architecture

.golangci.yml

@@ -59,6 +59,14 @@ linters:
     - usestdlibvars
     - whitespace
   settings:
+    dupl:
+      # 200 covers the 57-line render/output_path parallel template
+      # parsing as well as the test patterns in cmd/ (each repeated
+      # setup block in cli_integration_test.go and
+      # template_integration_test.go registers as ~20 lines, fitting
+      # under 200). Raise further if the linter starts flagging new
+      # template helpers down the line.
+      threshold: 200
     tagalign:
       sort: true
       strict: false
@@ -93,6 +101,41 @@ linters:
       local-variables-are-used: false
       generated-is-used: false
 
+  # Pass H6 of cleanup migration. forbidigo is configured (above) to
+  # ban fmt.Errorf in production code. As packages migrate to
+  # foundation/errors they are removed from the exclusion list below.
+  # Remove a line whenever you finish migrating a package.
+  #
+  # Migrated (not excluded, must pass the rule):
+  #   internal/state/, internal/linkverify/,
+  #   internal/templates/sequence.go, internal/forge/enhanced_mock.go,
+  #   internal/hugo/indexes.go, internal/build/delta/manager.go,
+  #   internal/config/composite_defaults.go, internal/daemon/daemon.go.
+  #
+  # v2 schema note: the v1 keys that used to live under `issues:` have
+  # moved here. Specifically:
+  #   issues.exclude-dirs-use-default -> removed (option no longer exists)
+  #   issues.exclude-dirs / -files   -> linters.exclusions.paths (mirror
+  #                                    under formatters.exclusions.paths
+  #                                    so formatters apply the same skips)
+  #   issues.exclude-rules           -> linters.exclusions.rules
+  exclusions:
+    paths:
+      - 'internal/hugo/stages_transition_test\.go$'
+    rules:
+      # The old //nolint:forbidigo directives in cmd/ now target fmt.Println;
+      # forbidigo fmt.Errorf never matches in those functions, so the
+      # comments are unused. Silence the unused-directive complaints from nolintlint.
+      - linters: [nolintlint]
+        path: 'cmd/docbuilder/commands/(build|init)\.go$'
+      - linters: [nolintlint]
+        path: 'examples/tools/debug_webhook\.go$'
+      # render.go and output_path.go have parallel template-parsing
+      # shapes by design; the dupl threshold flags them as 57-line copies.
+      # Both files were in this state before this cleanup.
+      - linters: [dupl]
+        path: 'internal/templates/(render|output_path)\.go$'
+
 formatters:
   enable:
     # - gci
@@ -104,4 +147,10 @@ formatters:
       sections:
         - standard
         - default
-        - prefix(git.home.luguber.info/inful/docbuilder)
+        - prefix(git.home.luguber.info/inful/docbuilder)
+  exclusions:
+    # Mirror the linters-side file skip so formatters leave the
+    # matching test file unchanged (matches v1's `issues.exclude-files`
+    # semantics, which applied to linters and formatters alike).
+    paths:
+      - 'internal/hugo/stages_transition_test\.go$'

cmd/docbuilder/commands/build.go

@@ -7,9 +7,12 @@ import (
 	"os"
 	"path/filepath"
 
+	"git.home.luguber.info/inful/docbuilder/internal/build"
 	"git.home.luguber.info/inful/docbuilder/internal/config"
 	"git.home.luguber.info/inful/docbuilder/internal/docs"
+	derrors "git.home.luguber.info/inful/docbuilder/internal/foundation/errors"
 	"git.home.luguber.info/inful/docbuilder/internal/hugo"
+	"git.home.luguber.info/inful/docbuilder/internal/workspace"
 )
 
 // BuildCmd implements the 'build' command.
@@ -45,7 +48,7 @@ func (b *BuildCmd) Run(_ *Global, root *CLI) error {
 	} else {
 		_, loadedCfg, err := config.LoadWithResult(root.Config)
 		if err != nil {
-			return fmt.Errorf("load config: %w", err)
+			return derrors.WrapError(err, derrors.CategoryConfig, "load config").Build()
 		}
 		cfg = loadedCfg
 		slog.Info("Loaded config from file", "config", root.Config)
@@ -85,7 +88,9 @@ func (b *BuildCmd) Run(_ *Global, root *CLI) error {
 	return RunBuild(cfg, outputDir, b.Incremental, root.Verbose, b.KeepWorkspace)
 }
 
-// RunBuild executes the build pipeline using the unified generator pipeline.
+// RunBuild executes the build pipeline using build.BuildService.
+// This is the canonical CLI entry point; it routes through the same service
+// the daemon uses (with a nil skip-evaluator and a noop recorder).
 //
 //nolint:forbidigo // fmt is used for user-facing messages
 func RunBuild(cfg *config.Config, outputDir string, incrementalMode, verbose, keepWorkspace bool) error {
@@ -107,44 +112,65 @@ func RunBuild(cfg *config.Config, outputDir string, incrementalMode, verbose, ke
 		"incremental", incrementalMode,
 		"keep_workspace", keepWorkspace)
 
-	// Create workspace manager
-	wsManager, err := CreateWorkspace(cfg)
-	if err != nil {
-		return err
-	}
-	if !keepWorkspace {
-		defer CleanupWorkspace(wsManager)
-	} else {
-		slog.Info("Workspace will be preserved for debugging", "path", wsManager.GetPath())
-		fmt.Printf("Workspace preserved at: %s\n", wsManager.GetPath())
+	// Build the workspace factory. Persistent managers (KeepWorkspace=true)
+	// skip cleanup on exit; ephemeral managers (KeepWorkspace=false) are
+	// removed by BuildService's deferred cleanup.
+	wsDir := cfg.Build.WorkspaceDir
+	workspaceFactory := func() *workspace.Manager {
+		if keepWorkspace {
+			return workspace.NewPersistentManager(wsDir, "working")
+		}
+		return workspace.NewManager(wsDir)
 	}
 
-	// Initialize Generator
-	generator := hugo.NewGenerator(cfg, outputDir).WithKeepStaging(keepWorkspace)
+	svc := build.NewBuildService().
+		WithWorkspaceFactory(workspaceFactory).
+		WithHugoGeneratorFactory(func(c *config.Config, dir string) build.HugoGenerator {
+			return hugo.NewGenerator(c, dir).WithKeepStaging(keepWorkspace)
+		}).
+		WithSkipEvaluatorFactory(func(string) build.SkipEvaluator {
+			// Skip evaluation requires daemon state; the CLI never has it.
+			return nil
+		})
+
+	req := build.BuildRequest{
+		Config:      cfg,
+		OutputDir:   outputDir,
+		Incremental: incrementalMode,
+		Options: build.BuildOptions{
+			Verbose:         verbose,
+			KeepWorkspace:   keepWorkspace,
+			SkipIfUnchanged: false,
+		},
+	}
 
-	// Run the unified pipeline
-	ctx := context.Background()
-	report, err := generator.GenerateFullSite(ctx, cfg.Repositories, wsManager.GetPath())
+	result, err := svc.Run(context.Background(), req)
 	if err != nil {
 		slog.Error("Build pipeline failed", "error", err)
-		// Show workspace location on error for debugging
 		if keepWorkspace {
-			fmt.Printf("\nError occurred. Workspace preserved at: %s\n", wsManager.GetPath())
+			fmt.Printf("\nError occurred. Workspace preserved (check above log).\n")
 			fmt.Printf("Hugo staging directory: %s_stage\n", outputDir)
 		}
 		return err
 	}
 
-	if report.FailedRepositories > 0 {
+	if result.Report != nil && result.Report.FailedRepositories > 0 {
 		slog.Warn("Some repositories were skipped due to errors",
-			"skipped", report.FailedRepositories,
+			"skipped", result.Report.FailedRepositories,
 			"total", len(cfg.Repositories))
 	}
 
+	// Preserve the original log shape: "pages" = rendered HTML pages (not
+	// markdown files). The CLI used to read report.RenderedPages directly;
+	// BuildService exposes that via BuildResult.Report.RenderedPages.
+	renderedPages := 0
+	if result.Report != nil {
+		renderedPages = result.Report.RenderedPages
+	}
 	slog.Info("Build completed successfully",
 		"output", outputDir,
-		"pages", report.RenderedPages,
-		"skipped_repos", report.FailedRepositories)
+		"pages", renderedPages,
+		"skipped_repos", result.RepositoriesSkipped)
 
 	fmt.Println("Build completed successfully")
 	return nil
@@ -196,12 +222,12 @@ func (b *BuildCmd) runLocalBuild(cfg *config.Config, outputDir string, verbose,
 	// Resolve absolute path to docs directory
 	docsPath, err := filepath.Abs(b.DocsDir)
 	if err != nil {
-		return fmt.Errorf("resolve docs dir: %w", err)
+		return derrors.WrapError(err, derrors.CategoryFileSystem, "resolve docs dir").Build()
 	}
 
 	// Verify docs directory exists
 	if st, statErr := os.Stat(docsPath); statErr != nil || !st.IsDir() {
-		return fmt.Errorf("docs dir not found or not a directory: %s (use -d to specify a different path)", docsPath)
+		return derrors.NewError(derrors.CategoryNotFound, "docs dir not found or not a directory (use -d to specify a different path)").WithContext("path", docsPath).Build()
 	}
 
 	slog.Info("Building from local directory",
@@ -217,12 +243,12 @@ func (b *BuildCmd) runLocalBuild(cfg *config.Config, outputDir string, verbose,
 	slog.Info("Discovering documentation files")
 	docFiles, discErr := discovery.DiscoverDocs(repoPaths)
 	if discErr != nil {
-		return fmt.Errorf("discovery failed: %w", discErr)
+		return derrors.WrapError(discErr, derrors.CategoryInternal, "discovery failed").Build()
 	}
 
 	if len(docFiles) == 0 {
 		slog.Warn("No documentation files found in directory", "dir", docsPath)
-		return fmt.Errorf("no documentation files found in %s", docsPath)
+		return derrors.NewError(derrors.CategoryNotFound, "no documentation files found").WithContext("path", docsPath).Build()
 	}
 
 	slog.Info("Documentation discovered", "files", len(docFiles))
@@ -239,7 +265,7 @@ func (b *BuildCmd) runLocalBuild(cfg *config.Config, outputDir string, verbose,
 		if keepWorkspace {
 			fmt.Printf("\nError occurred. Hugo staging directory: %s_stage\n", outputDir)
 		}
-		return fmt.Errorf("site generation failed: %w", err)
+		return derrors.WrapError(err, derrors.CategoryInternal, "site generation failed").Build()
 	}
 
 	slog.Info("Hugo site generated successfully",

cmd/docbuilder/commands/common.go

@@ -15,6 +15,7 @@ import (
 
 	"git.home.luguber.info/inful/docbuilder/internal/config"
 	"git.home.luguber.info/inful/docbuilder/internal/forge"
+	derrors "git.home.luguber.info/inful/docbuilder/internal/foundation/errors"
 	"git.home.luguber.info/inful/docbuilder/internal/git"
 	"git.home.luguber.info/inful/docbuilder/internal/workspace"
 )
@@ -83,7 +84,7 @@ func LoadEnvFile() error {
 	for _, p := range envPaths {
 		if _, err := os.Stat(p); err == nil {
 			if err := godotenv.Load(p); err != nil {
-				return fmt.Errorf("failed loading %s: %w", p, err)
+				return derrors.WrapError(err, derrors.CategoryFileSystem, "failed loading").WithContext("path", p).Build()
 			}
 			return nil
 		}
@@ -215,7 +216,7 @@ func ApplyAutoDiscovery(ctx context.Context, cfg *config.Config) error {
 	if len(cfg.Repositories) == 0 && len(cfg.Forges) > 0 {
 		repos, err := AutoDiscoverRepositories(ctx, cfg)
 		if err != nil {
-			return fmt.Errorf("auto-discovery failed: %w", err)
+			return derrors.WrapError(err, derrors.CategoryInternal, "auto-discovery failed").Build()
 		}
 		cfg.Repositories = repos
 	}

cmd/docbuilder/commands/daemon.go

@@ -2,14 +2,14 @@ package commands
 
 import (
 	"context"
-	"fmt"
 	"log/slog"
 	"os/signal"
 	"syscall"
 	"time"
 
 	"git.home.luguber.info/inful/docbuilder/internal/config"
 	"git.home.luguber.info/inful/docbuilder/internal/daemon"
+	derrors "git.home.luguber.info/inful/docbuilder/internal/foundation/errors"
 )
 
 // DaemonCmd implements the 'daemon' command.
@@ -25,7 +25,7 @@ func (d *DaemonCmd) Run(_ *Global, root *CLI) error {
 
 	result, cfg, err := config.LoadWithResult(root.Config)
 	if err != nil {
-		return fmt.Errorf("load config: %w", err)
+		return derrors.WrapError(err, derrors.CategoryConfig, "load config").Build()
 	}
 	// Print any normalization warnings
 	for _, w := range result.Warnings {
@@ -44,7 +44,7 @@ func RunDaemon(cfg *config.Config, dataDir, configPath string) error {
 	// Create and start the daemon with config file watching
 	d, err := daemon.NewDaemonWithConfigFile(cfg, configPath)
 	if err != nil {
-		return fmt.Errorf("failed to create daemon: %w", err)
+		return derrors.WrapError(err, derrors.CategoryInternal, "failed to create daemon").Build()
 	}
 
 	// Start daemon in a goroutine
@@ -59,7 +59,7 @@ func RunDaemon(cfg *config.Config, dataDir, configPath string) error {
 	select {
 	case err := <-errChan:
 		if err != nil {
-			return fmt.Errorf("daemon error: %w", err)
+			return derrors.WrapError(err, derrors.CategoryInternal, "daemon error").Build()
 		}
 	case <-ctx.Done():
 		slog.Info("Shutdown signal received, stopping daemon...")
@@ -70,7 +70,7 @@ func RunDaemon(cfg *config.Config, dataDir, configPath string) error {
 	defer stopCancel()
 
 	if err := d.Stop(stopCtx); err != nil {
-		return fmt.Errorf("failed to stop daemon: %w", err)
+		return derrors.WrapError(err, derrors.CategoryInternal, "failed to stop daemon").Build()
 	}
 
 	slog.Info("Daemon stopped successfully")

cmd/docbuilder/commands/discover.go

@@ -2,11 +2,11 @@ package commands
 
 import (
 	"context"
-	"fmt"
 	"log/slog"
 
 	"git.home.luguber.info/inful/docbuilder/internal/config"
 	"git.home.luguber.info/inful/docbuilder/internal/docs"
+	derrors "git.home.luguber.info/inful/docbuilder/internal/foundation/errors"
 	"git.home.luguber.info/inful/docbuilder/internal/git"
 )
 
@@ -15,27 +15,27 @@ type DiscoverCmd struct {
 	Repository string `short:"r" help:"Specific repository to discover (optional)"`
 }
 
-func (d *DiscoverCmd) Run(_ *Global, root *CLI) error {
+func (d *DiscoverCmd) Run(ctx context.Context, _ *Global, root *CLI) error {
 	// Load .env file if it exists (before config)
 	if err := LoadEnvFile(); err == nil && root.Verbose {
 		slog.Info("Loaded environment variables from .env file")
 	}
 
 	result, cfg, err := config.LoadWithResult(root.Config)
 	if err != nil {
-		return fmt.Errorf("load config: %w", err)
+		return derrors.WrapError(err, derrors.CategoryConfig, "load config").Build()
 	}
 	// Print any normalization warnings
 	for _, w := range result.Warnings {
 		slog.Warn(w)
 	}
-	if err := ApplyAutoDiscovery(context.Background(), cfg); err != nil {
+	if err := ApplyAutoDiscovery(ctx, cfg); err != nil {
 		return err
 	}
-	return RunDiscover(cfg, d.Repository)
+	return RunDiscover(ctx, cfg, d.Repository)
 }
 
-func RunDiscover(cfg *config.Config, specificRepo string) error {
+func RunDiscover(ctx context.Context, cfg *config.Config, specificRepo string) error {
 	slog.Info("Starting documentation discovery", "repositories", len(cfg.Repositories))
 
 	// Create workspace manager
@@ -62,7 +62,7 @@ func RunDiscover(cfg *config.Config, specificRepo string) error {
 			}
 		}
 		if len(reposToProcess) == 0 {
-			return fmt.Errorf("repository '%s' not found in configuration", specificRepo)
+			return derrors.NewError(derrors.CategoryConfig, "repository not found in configuration").WithContext("repository", specificRepo).Build()
 		}
 	} else {
 		reposToProcess = cfg.Repositories
@@ -75,7 +75,7 @@ func RunDiscover(cfg *config.Config, specificRepo string) error {
 		slog.Info("Cloning repository", "name", repo.Name, "url", repo.URL)
 
 		var result git.CloneResult
-		result, err = gitClient.CloneRepoWithMetadata(*repo)
+		result, err = gitClient.CloneRepoWithMetadata(ctx, *repo)
 		if err != nil {
 			slog.Error("Failed to clone repository", "name", repo.Name, "error", err)
 			return err