Pipeline Planning

internal/app/app.go

@@ -178,24 +178,35 @@ func runBuildModule(ctx context) error {
 	return nil
 }
 
+type buildHAKOptions struct {
+	filteredHAKs []string
+	planOnly     bool
+}
+
 func runBuildHAKs(ctx context) error {
 	p, err := loadProject(ctx.cwd)
 	if err != nil {
 		return err
 	}
 
-	filteredHAKs, err := parseBuildHAKArgs(ctx.args[1:])
+	opts, err := parseBuildHAKArgs(ctx.args[1:])
 	if err != nil {
 		return err
 	}
-	p, err = p.CloneWithHAKNames(filteredHAKs)
+	p, err = p.CloneWithHAKNames(opts.filteredHAKs)
 	if err != nil {
 		return err
 	}
 
-	result, err := pipeline.BuildHAKsWithProgress(p, func(message string) {
+	progress := func(message string) {
 		fmt.Fprintf(ctx.stdout, "[build-haks] %s\n", message)
-	})
+	}
+	var result pipeline.BuildResult
+	if opts.planOnly {
+		result, err = pipeline.PlanHAKsWithProgress(p, progress)
+	} else {
+		result, err = pipeline.BuildHAKsWithProgress(p, progress)
+	}
 	if err != nil {
 		return err
 	}
@@ -209,32 +220,34 @@ func runBuildHAKs(ctx context) error {
 	return nil
 }
 
-func parseBuildHAKArgs(args []string) ([]string, error) {
+func parseBuildHAKArgs(args []string) (buildHAKOptions, error) {
+	opts := buildHAKOptions{}
 	if len(args) == 0 {
-		return nil, nil
+		return opts, nil
 	}
 
-	var filtered []string
 	for index := 0; index < len(args); index++ {
 		arg := args[index]
 		switch arg {
 		case "-h", "--help":
-			return nil, errors.New("usage: build-haks [--hak <hak-name> ...]")
+			return opts, errors.New("usage: build-haks [--hak <hak-name> ...] [--plan-only]")
 		case "--hak":
 			index++
 			if index >= len(args) {
-				return nil, errors.New("--hak requires a value")
+				return opts, errors.New("--hak requires a value")
 			}
-			filtered = append(filtered, args[index])
+			opts.filteredHAKs = append(opts.filteredHAKs, args[index])
+		case "--plan-only":
+			opts.planOnly = true
 		default:
 			if value, ok := parseInlineFlagValue(arg, "--hak"); ok {
-				filtered = append(filtered, value)
+				opts.filteredHAKs = append(opts.filteredHAKs, value)
 				continue
 			}
-			return nil, fmt.Errorf("unknown build-haks argument %q", arg)
+			return opts, fmt.Errorf("unknown build-haks argument %q", arg)
 		}
 	}
-	return filtered, nil
+	return opts, nil
 }
 
 func parseInlineFlagValue(arg, name string) (string, bool) {

internal/pipeline/build.go

@@ -145,7 +145,25 @@ func BuildHAKsWithProgress(p *project.Project, progress ProgressFunc) (BuildResu
 	return buildHAKs(p, progress)
 }
 
+func PlanHAKs(p *project.Project) (BuildResult, error) {
+	return planHAKs(p, nil)
+}
+
+func PlanHAKsWithProgress(p *project.Project, progress ProgressFunc) (BuildResult, error) {
+	return planHAKs(p, progress)
+}
+
 func buildHAKs(p *project.Project, progress ProgressFunc) (BuildResult, error) {
+	return planOrBuildHAKs(p, progress, true)
+}
+
+func planHAKs(p *project.Project, progress ProgressFunc) (BuildResult, error) {
+	return planOrBuildHAKs(p, progress, false)
+}
+
+func planOrBuildHAKs(p *project.Project, progress ProgressFunc, writeArchives bool) (BuildResult, error) {
+	preserveExistingHAKs := envBool("SOW_BUILD_HAKS_KEEP_EXISTING")
+
 	progressf(progress, "Validating project...")
 	if err := validateForBuild(p); err != nil {
 		return BuildResult{}, err
@@ -176,21 +194,48 @@ func buildHAKs(p *project.Project, progress ProgressFunc) (BuildResult, error) {
 	if err != nil {
 		return BuildResult{}, err
 	}
-	previousManifest, err := loadPreviousBuildManifest(p.BuildDir())
-	if err != nil {
-		return BuildResult{}, err
-	}
-	progressf(progress, "Reusing unchanged generated HAKs where possible...")
 
 	manifest := BuildManifest{
 		ModuleHAKs: moduleHakOrder,
 		HAKs:       make([]BuildManifestHAK, 0, len(chunks)),
 	}
 	currentNames := make(map[string]struct{}, len(chunks))
-	for index, chunk := range chunks {
+	for _, chunk := range chunks {
-		hakPath := filepath.Join(p.BuildDir(), chunk.Name+".hak")
 		manifestEntry := buildManifestEntry(chunk)
 		currentNames[chunk.Name] = struct{}{}
+		manifest.HAKs = append(manifest.HAKs, manifestEntry)
+	}
+
+	manifestPath := filepath.Join(p.BuildDir(), "haks.json")
+	manifestBytes, err := json.MarshalIndent(manifest, "", "  ")
+	if err != nil {
+		return BuildResult{}, fmt.Errorf("marshal hak manifest: %w", err)
+	}
+	manifestBytes = append(manifestBytes, '\n')
+
+	if !writeArchives {
+		progressf(progress, "Cleaning previous generated HAKs...")
+		if err := cleanupGeneratedHAKs(p.BuildDir(), p.Config.Module.ResRef); err != nil {
+			return BuildResult{}, err
+		}
+		progressf(progress, "Writing HAK manifest...")
+		if err := os.WriteFile(manifestPath, manifestBytes, 0o644); err != nil {
+			return BuildResult{}, fmt.Errorf("write hak manifest: %w", err)
+		}
+		result.Manifest = manifestPath
+		return result, nil
+	}
+
+	previousManifest, err := loadPreviousBuildManifest(p.BuildDir())
+	if err != nil {
+		return BuildResult{}, err
+	}
+	progressf(progress, "Reusing unchanged generated HAKs where possible...")
+
+	result.HAKPaths = make([]string, 0, len(chunks))
+	for index, chunk := range chunks {
+		hakPath := filepath.Join(p.BuildDir(), chunk.Name+".hak")
+		manifestEntry := manifest.HAKs[index]
 		reused, err := reuseExistingHAK(previousManifest, manifestEntry, hakPath)
 		if err != nil {
 			return BuildResult{}, err
@@ -213,20 +258,15 @@ func buildHAKs(p *project.Project, progress ProgressFunc) (BuildResult, error) {
 		}
 
 		result.HAKPaths = append(result.HAKPaths, hakPath)
-		manifest.HAKs = append(manifest.HAKs, manifestEntry)
 	}
 	progressf(progress, "Cleaning stale generated HAKs...")
+	if !preserveExistingHAKs {
 		if err := cleanupStaleGeneratedHAKs(p.BuildDir(), p.Config.Module.ResRef, currentNames); err != nil {
 			return BuildResult{}, err
 		}
+	}
 
 	progressf(progress, "Writing HAK manifest...")
-	manifestPath := filepath.Join(p.BuildDir(), "haks.json")
-	manifestBytes, err := json.MarshalIndent(manifest, "", "  ")
-	if err != nil {
-		return BuildResult{}, fmt.Errorf("marshal hak manifest: %w", err)
-	}
-	manifestBytes = append(manifestBytes, '\n')
 	if err := os.WriteFile(manifestPath, manifestBytes, 0o644); err != nil {
 		return BuildResult{}, fmt.Errorf("write hak manifest: %w", err)
 	}
@@ -240,6 +280,16 @@ func progressf(progress ProgressFunc, message string) {
 	}
 }
 
+func envBool(name string) bool {
+	value := strings.TrimSpace(strings.ToLower(os.Getenv(name)))
+	switch value {
+	case "1", "true", "yes", "on":
+		return true
+	default:
+		return false
+	}
+}
+
 func collectModuleResources(p *project.Project, moduleHakOrder []string) ([]erf.Resource, error) {
 	var moduleResources []erf.Resource
 

internal/pipeline/pipeline_test.go

@@ -1160,6 +1160,75 @@ func TestBuildExcludesOptionalHAKsFromModuleOrder(t *testing.T) {
 	}
 }
 
+func TestPlanHAKsWritesManifestWithoutArchives(t *testing.T) {
+	root := t.TempDir()
+	mustMkdir(t, filepath.Join(root, "src"))
+	mustMkdir(t, filepath.Join(root, "assets", "core"))
+	mustMkdir(t, filepath.Join(root, "build"))
+
+	mustWriteFile(t, filepath.Join(root, "nwn-tool.json"), `{
+  "module": {
+    "name": "Test Module",
+    "resref": "testmod",
+    "hak_order": ["group:core"]
+  },
+  "paths": {
+    "source": "src",
+    "assets": "assets",
+    "build": "build"
+  },
+  "haks": [
+    {
+      "name": "core",
+      "priority": 1,
+      "max_bytes": 0,
+      "split": false,
+      "include": ["core/**"]
+    }
+  ]
+}
+`)
+	mustWriteFile(t, filepath.Join(root, "assets", "core", "a.tga"), "core-data")
+
+	p, err := project.Load(root)
+	if err != nil {
+		t.Fatalf("load project: %v", err)
+	}
+	if err := p.ValidateLayout(); err != nil {
+		t.Fatalf("validate layout: %v", err)
+	}
+	if err := p.Scan(); err != nil {
+		t.Fatalf("scan: %v", err)
+	}
+
+	result, err := PlanHAKs(p)
+	if err != nil {
+		t.Fatalf("plan haks: %v", err)
+	}
+	if len(result.HAKPaths) != 0 {
+		t.Fatalf("expected no hak outputs for plan-only, got %d", len(result.HAKPaths))
+	}
+
+	manifestPath := filepath.Join(root, "build", "haks.json")
+	rawManifest, err := os.ReadFile(manifestPath)
+	if err != nil {
+		t.Fatalf("read manifest: %v", err)
+	}
+	var manifest BuildManifest
+	if err := json.Unmarshal(rawManifest, &manifest); err != nil {
+		t.Fatalf("parse manifest: %v", err)
+	}
+	if len(manifest.HAKs) != 1 {
+		t.Fatalf("expected 1 manifest hak entry, got %d", len(manifest.HAKs))
+	}
+	if manifest.HAKs[0].ContentHash == "" {
+		t.Fatal("expected plan-only manifest to include content hash")
+	}
+	if _, err := os.Stat(filepath.Join(root, "build", "core.hak")); !os.IsNotExist(err) {
+		t.Fatalf("expected no built hak archive, got err=%v", err)
+	}
+}
+
 func TestBuildSkipsEmptyHAKGroupsInModuleOrder(t *testing.T) {
 	root := t.TempDir()
 	mustMkdir(t, filepath.Join(root, "src"))