command and help ux pass (#21)

Reviewed-on: #21 Co-authored-by: vickydotbat <vickydotbat@tutamail.com> Co-committed-by: vickydotbat <vickydotbat@tutamail.com>
2026-06-25 09:29:39 +00:00
parent 6afac1a4d9
commit f257672427
29 changed files with 1077 additions and 3151 deletions
@@ -9,7 +9,6 @@ import (
 	"os/exec"
 	"path/filepath"
 	"runtime"
-	"sort"
 	"strconv"
 	"strings"
 	"sync"
@@ -184,11 +183,6 @@ var commands = []command{
 		description: "Inspect, explain, and validate the resolved project configuration.",
 		run:         runConfig,
 	},
-	{
-		name:        "music",
-		description: "List, scan, build, and validate configured music datasets.",
-		run:         runMusic,
-	},
 	{
 		name:        "compare",
 		description: "Compare current source content against the built archives.",
@@ -470,8 +464,6 @@ type buildHAKOptions struct {
 	filteredArchives     []string
 	sourceManifest       string
 	contentAddressedRoot string
-	musicDatasets        []string
-	skipMusic            bool
 	planOnly             bool
 	logLevel             logLevel
 }
@@ -721,46 +713,11 @@ func (c *buildHAKConsole) emitResult(result pipeline.BuildResult) {
 	spin.linebreak()
 	fmt.Fprintln(c.stdout, "Build HAKs ----------")
 	if c.level != logLevelQuiet {
-		c.emitCreditsSummary(result)
 		c.emitCoreSteps(result)
 	}
 	c.emitFinalSummary(result)
 }

-func (c *buildHAKConsole) emitCreditsSummary(result pipeline.BuildResult) {
-	summary := result.CreditsSummary
-	if len(summary.ArtifactPaths) == 0 {
-		return
-	}
-	fmt.Fprintln(c.stdout, "Refreshing credits cache")
-	if len(summary.ScannedDirs) > 0 {
-		fmt.Fprintf(c.stdout, "  scanned: %s\n", strings.Join(summary.ScannedDirs, ", "))
-	}
-	fmt.Fprintf(c.stdout, "  tracks: %d\n", summary.TrackCount)
-	if len(summary.GeneratedPaths) > 0 {
-		for _, path := range summary.GeneratedPaths {
-			fmt.Fprintf(c.stdout, "  output: %s\n", c.relPath(path))
-		}
-	}
-	switch {
-	case summary.ChangedFiles == 0:
-		fmt.Fprintln(c.stdout, "  status: unchanged")
-	default:
-		fmt.Fprintf(c.stdout, "  updated: %d artifact(s)\n", summary.ChangedFiles)
-	}
-	if summary.TrackCount > 0 {
-		if c.level >= logLevelVerbose {
-			fmt.Fprintln(c.stdout, "  mappings:")
-			for _, mapping := range summary.Mappings {
-				fmt.Fprintf(c.stdout, "    %s -> %s\n", mapping.Source, mapping.Output)
-			}
-		} else {
-			fmt.Fprintf(c.stdout, "  mapped: %d music file(s); use --verbose to list mappings\n", summary.TrackCount)
-		}
-	}
-	fmt.Fprintln(c.stdout)
-}
-
 func (c *buildHAKConsole) emitCoreSteps(result pipeline.BuildResult) {
 	fmt.Fprintln(c.stdout, "Validating project")
 	fmt.Fprintln(c.stdout, "Collecting asset resources")
@@ -808,9 +765,6 @@ func (c *buildHAKConsole) emitFinalSummary(result pipeline.BuildResult) {
 	if result.Manifest != "" {
 		fmt.Fprintf(c.stdout, "manifest: %s\n", c.relPath(result.Manifest))
 	}
-	if len(result.CreditsArtifactPaths) > 0 {
-		fmt.Fprintf(c.stdout, "credits artifacts: %d\n", len(result.CreditsArtifactPaths))
-	}
 	if len(result.AutogenManifestPaths) > 0 {
 		fmt.Fprintf(c.stdout, "autogen manifests: %d\n", len(result.AutogenManifestPaths))
 	}
@@ -1050,8 +1004,6 @@ func runBuildHAKs(ctx context) error {
 		ArchiveNames:         opts.filteredArchives,
 		SourceManifestPath:   opts.sourceManifest,
 		ContentAddressedRoot: opts.contentAddressedRoot,
-		SkipMusic:            opts.skipMusic,
-		MusicDatasetIDs:      opts.musicDatasets,
 	}
 	if opts.planOnly {
 		result, err = pipeline.PlanHAKsWithOptions(p, pipelineOpts)
@@ -1076,7 +1028,7 @@ func parseBuildHAKArgs(args []string) (buildHAKOptions, error) {
 		arg := args[index]
 		switch arg {
 		case "-h", "--help":
-			return opts, errors.New("usage: build-haks [--hak <hak-name> ...] [--archive <archive-name> ...] [--source-manifest <path>] [--content-addressed-root <path>] [--plan-only] [--skip-music] [--music-dataset <id> ...] [--quiet|--verbose|--debug]")
+			return opts, errors.New("usage: build-haks [--hak <hak-name> ...] [--archive <archive-name> ...] [--source-manifest <path>] [--content-addressed-root <path>] [--plan-only] [--quiet|--verbose|--debug]")
 		case "--hak":
 			index++
 			if index >= len(args) {
@@ -1091,14 +1043,6 @@ func parseBuildHAKArgs(args []string) (buildHAKOptions, error) {
 			opts.filteredArchives = append(opts.filteredArchives, args[index])
 		case "--plan-only":
 			opts.planOnly = true
-		case "--skip-music":
-			opts.skipMusic = true
-		case "--music-dataset":
-			index++
-			if index >= len(args) {
-				return opts, errors.New("--music-dataset requires a value")
-			}
-			opts.musicDatasets = append(opts.musicDatasets, args[index])
 		case "--quiet":
 			opts.logLevel = logLevelQuiet
 		case "--verbose":
@@ -1146,13 +1090,6 @@ func parseBuildHAKArgs(args []string) (buildHAKOptions, error) {
 				opts.contentAddressedRoot = value
 				continue
 			}
-			if value, ok, err := requireInlineFlagValue(arg, "--music-dataset"); ok || err != nil {
-				if err != nil {
-					return opts, err
-				}
-				opts.musicDatasets = append(opts.musicDatasets, value)
-				continue
-			}
 			if arg == "--quiet=true" {
 				opts.logLevel = logLevelQuiet
 				continue
@@ -1182,149 +1119,6 @@ func requireInlineFlagValue(arg, name string) (string, bool, error) {
 	return value, true, nil
 }

-type musicCommandOptions struct {
-	datasets []string
-	json     bool
-	dryRun   bool
-	check    bool
-	force    bool
-}
-
-func runMusic(ctx context) error {
-	if len(ctx.args) < 2 {
-		return errors.New("usage: music <list-datasets|scan|build|credits|validate|manifest|normalize> [--dataset <id>] [--json] [--dry-run] [--check] [--force]")
-	}
-	p, err := loadProject(ctx)
-	if err != nil {
-		return err
-	}
-	if err := p.Scan(); err != nil {
-		return err
-	}
-	subcommand := ctx.args[1]
-	opts, err := parseMusicCommandArgs(ctx.args[2:])
-	if err != nil {
-		return err
-	}
-	switch subcommand {
-	case "list-datasets":
-		return emitMusicDatasets(ctx, p, opts)
-	case "scan":
-		result, err := pipeline.BuildMusic(p, pipeline.MusicBuildOptions{DatasetIDs: opts.datasets, Write: false})
-		if err != nil {
-			return err
-		}
-		return emitMusicResult(ctx, "scan", result, opts)
-	case "build", "credits":
-		write := true
-		if subcommand == "build" && opts.dryRun {
-			write = false
-		}
-		if subcommand == "credits" && opts.check {
-			write = false
-		}
-		result, err := pipeline.BuildMusic(p, pipeline.MusicBuildOptions{DatasetIDs: opts.datasets, Write: write})
-		if err != nil {
-			return err
-		}
-		return emitMusicResult(ctx, subcommand, result, opts)
-	case "manifest", "normalize":
-		result, err := pipeline.BuildMusic(p, pipeline.MusicBuildOptions{DatasetIDs: opts.datasets, Write: false})
-		if err != nil {
-			return err
-		}
-		return emitMusicResult(ctx, subcommand, result, opts)
-	case "validate":
-		if err := p.ValidateLayout(); err != nil {
-			return err
-		}
-		result, err := pipeline.BuildMusic(p, pipeline.MusicBuildOptions{DatasetIDs: opts.datasets, Write: false})
-		if err != nil {
-			return err
-		}
-		return emitMusicResult(ctx, "validate", result, opts)
-	default:
-		return fmt.Errorf("unknown music subcommand %q", subcommand)
-	}
-}
-
-func parseMusicCommandArgs(args []string) (musicCommandOptions, error) {
-	opts := musicCommandOptions{}
-	for index := 0; index < len(args); index++ {
-		arg := args[index]
-		switch arg {
-		case "--dataset":
-			index++
-			if index >= len(args) || strings.TrimSpace(args[index]) == "" {
-				return opts, errors.New("--dataset requires a value")
-			}
-			opts.datasets = append(opts.datasets, args[index])
-		case "--json":
-			opts.json = true
-		case "--dry-run":
-			opts.dryRun = true
-		case "--check":
-			opts.check = true
-		case "--force":
-			opts.force = true
-		default:
-			if value, ok, err := requireInlineFlagValue(arg, "--dataset"); ok || err != nil {
-				if err != nil {
-					return opts, err
-				}
-				opts.datasets = append(opts.datasets, value)
-				continue
-			}
-			return opts, fmt.Errorf("unknown music argument %q", arg)
-		}
-	}
-	return opts, nil
-}
-
-func emitMusicDatasets(ctx context, p *project.Project, opts musicCommandOptions) error {
-	effective := p.EffectiveConfig()
-	if opts.json {
-		return emitConfigValue(ctx.stdout, effective.Music.Datasets, "json")
-	}
-	if len(effective.Music.Datasets) == 0 {
-		fmt.Fprintln(ctx.stdout, "music datasets: none")
-		return nil
-	}
-	fmt.Fprintln(ctx.stdout, "music datasets:")
-	ids := make([]string, 0, len(effective.Music.Datasets))
-	for id := range effective.Music.Datasets {
-		ids = append(ids, id)
-	}
-	sort.Strings(ids)
-	for _, id := range ids {
-		ds := effective.Music.Datasets[id]
-		fmt.Fprintf(ctx.stdout, "  %s: source=%s output=%s prefix=%s\n", id, ds.Source, ds.Output, ds.Prefix)
-	}
-	return nil
-}
-
-func emitMusicResult(ctx context, action string, result pipeline.BuildResult, opts musicCommandOptions) error {
-	if opts.json {
-		return emitConfigValue(ctx.stdout, result.CreditsSummary, "json")
-	}
-	fmt.Fprintf(ctx.stdout, "music %s\n", action)
-	if len(result.CreditsSummary.ScannedDirs) > 0 {
-		fmt.Fprintf(ctx.stdout, "scanned: %s\n", strings.Join(result.CreditsSummary.ScannedDirs, ", "))
-	}
-	fmt.Fprintf(ctx.stdout, "tracks: %d\n", result.CreditsSummary.TrackCount)
-	if action != "scan" && len(result.CreditsArtifactPaths) > 0 {
-		fmt.Fprintf(ctx.stdout, "credits artifacts: %d\n", len(result.CreditsArtifactPaths))
-	}
-	if len(result.CreditsSummary.Mappings) > 0 && ctx.logLevel >= logLevelVerbose {
-		fmt.Fprintln(ctx.stdout, "mappings:")
-		for _, mapping := range result.CreditsSummary.Mappings {
-			fmt.Fprintf(ctx.stdout, "  %s -> %s\n", mapping.Source, mapping.Output)
-		}
-	}
-	fmt.Fprintln(ctx.stdout, "status: ok")
-	return nil
-}
-
 func runExtract(ctx context) error {
 	p, err := loadProject(ctx)
 	if err != nil {
@@ -54,8 +54,6 @@ func TestParseBuildHAKArgsHelpListsContentAddressedRoot(t *testing.T) {
 		"--source-manifest",
 		"--content-addressed-root",
 		"--plan-only",
-		"--skip-music",
-		"--music-dataset",
 		"--quiet",
 		"--verbose",
 		"--debug",
@@ -66,6 +64,18 @@ func TestParseBuildHAKArgsHelpListsContentAddressedRoot(t *testing.T) {
 	}
 }

+func TestParseBuildHAKArgsRejectsRemovedMusicFlags(t *testing.T) {
+	for _, args := range [][]string{
+		{"--skip-music"},
+		{"--music-dataset", "westgate"},
+		{"--music-dataset=westgate"},
+	} {
+		if _, err := parseBuildHAKArgs(args); err == nil {
+			t.Errorf("expected removed music arguments %v to fail", args)
+		}
+	}
+}
+
 func TestRunBuildTopPackageUsesCachedCompiledOutputs(t *testing.T) {
 	root := t.TempDir()
 	mkdirAll(t, filepath.Join(root, "build"))
@@ -113,7 +123,7 @@ topdata:
 	}
 }

-func TestRunBuildHAKsNormalOutputOmitsPerFileMappings(t *testing.T) {
+func TestRunBuildHAKsPacksAuthoredBMU(t *testing.T) {
 	root := t.TempDir()
 	mkdirAll(t, filepath.Join(root, "assets", "envi", "music", "westgate"))
 	mkdirAll(t, filepath.Join(root, "build"))
@@ -135,23 +145,7 @@ haks:
    include:
      - envi/**
 `)
-	writeFile(t, filepath.Join(root, "assets", "envi", "music", "westgate", "AleandAnecdotes.mp3"), "source-mp3")
-	writeFile(t, filepath.Join(root, "assets", "envi", "music", "westgate", "CREDITS.md"), "# NWN Music Pack Credits\n\n| Artist | Title | Output File | Original File | Album | Date | License / Copyright | Notes |\n|---|---|---|---|---|---|---|---|\n| Darren Curtis | Ale and Anecdotes | `mus_wg_andnc.bmu` | `AleandAnecdotes.mp3` | Darren's Commercially Free Music |  | Darren Curtis Music |  |\n")
-
-	ffprobePath := filepath.Join(root, "ffprobe")
-	writeFile(t, ffprobePath, "#!/bin/sh\nprintf '%s\\n' '{\"format\":{\"tags\":{\"artist\":\"Unknown\",\"title\":\"Broken Metadata\"}}}'\n")
-	if err := os.Chmod(ffprobePath, 0o755); err != nil {
-		t.Fatalf("chmod ffprobe: %v", err)
-	}
-
-	ffmpegPath := filepath.Join(root, "ffmpeg")
-	writeFile(t, ffmpegPath, "#!/bin/sh\nfor last; do :; done\nprintf 'bmu-data' > \"$last\"\n")
-	if err := os.Chmod(ffmpegPath, 0o755); err != nil {
-		t.Fatalf("chmod ffmpeg: %v", err)
-	}
-
-	t.Setenv("SOW_FFMPEG", ffmpegPath)
-	t.Setenv("SOW_FFPROBE", ffprobePath)
+	writeFile(t, filepath.Join(root, "assets", "envi", "music", "westgate", "westgate_theme.bmu"), "authored-bmu")

 	var stdout bytes.Buffer
 	ctx := context{
@@ -165,9 +159,12 @@ haks:
 		t.Fatalf("runBuildHAKs failed: %v", err)
 	}

-	output := stdout.String()
-	if strings.Contains(output, "AleandAnecdotes.mp3") || strings.Contains(output, "mus_wg_andnc.bmu") {
-		t.Fatalf("did not expect verbose mapping in normal mode, got %q", output)
+	manifest, err := os.ReadFile(filepath.Join(root, "build", "haks.json"))
+	if err != nil {
+		t.Fatalf("read HAK manifest: %v", err)
+	}
+	if !strings.Contains(string(manifest), "envi/music/westgate/westgate_theme.bmu") {
+		t.Fatalf("authored BMU missing from HAK manifest:\n%s", manifest)
 	}
 }

@@ -184,64 +181,6 @@ func setTreeTime(t *testing.T, root string, modTime time.Time) {
 	}
 }

-func TestRunBuildHAKsVerboseListsMappings(t *testing.T) {
-	root := t.TempDir()
-	mkdirAll(t, filepath.Join(root, "assets", "envi", "music", "westgate"))
-	mkdirAll(t, filepath.Join(root, "build"))
-	mkdirAll(t, filepath.Join(root, "src"))
-
-	writeFile(t, filepath.Join(root, "nwn-tool.yaml"), `
-module:
-  name: Test Module
-  resref: testmod
-paths:
-  source: src
-  assets: assets
-  build: build
-haks:
-  - name: envi
-    priority: 1
-    max_bytes: 1048576
-    split: false
-    include:
-      - envi/**
-`)
-	writeFile(t, filepath.Join(root, "assets", "envi", "music", "westgate", "AleandAnecdotes.mp3"), "source-mp3")
-	writeFile(t, filepath.Join(root, "assets", "envi", "music", "westgate", "CREDITS.md"), "# NWN Music Pack Credits\n\n| Artist | Title | Output File | Original File | Album | Date | License / Copyright | Notes |\n|---|---|---|---|---|---|---|---|\n| Darren Curtis | Ale and Anecdotes | `mus_wg_andnc.bmu` | `AleandAnecdotes.mp3` | Darren's Commercially Free Music |  | Darren Curtis Music |  |\n")
-
-	ffprobePath := filepath.Join(root, "ffprobe")
-	writeFile(t, ffprobePath, "#!/bin/sh\nprintf '%s\\n' '{\"format\":{\"tags\":{\"artist\":\"Unknown\",\"title\":\"Broken Metadata\"}}}'\n")
-	if err := os.Chmod(ffprobePath, 0o755); err != nil {
-		t.Fatalf("chmod ffprobe: %v", err)
-	}
-
-	ffmpegPath := filepath.Join(root, "ffmpeg")
-	writeFile(t, ffmpegPath, "#!/bin/sh\nfor last; do :; done\nprintf 'bmu-data' > \"$last\"\n")
-	if err := os.Chmod(ffmpegPath, 0o755); err != nil {
-		t.Fatalf("chmod ffmpeg: %v", err)
-	}
-
-	t.Setenv("SOW_FFMPEG", ffmpegPath)
-	t.Setenv("SOW_FFPROBE", ffprobePath)
-
-	var stdout bytes.Buffer
-	ctx := context{
-		stdout: &stdout,
-		stderr: &bytes.Buffer{},
-		cwd:    root,
-		args:   []string{"build-haks", "--verbose"},
-	}
-
-	if err := runBuildHAKs(ctx); err != nil {
-		t.Fatalf("runBuildHAKs failed: %v", err)
-	}
-
-	output := stdout.String()
-	if !strings.Contains(output, "AleandAnecdotes.mp3") || !strings.Contains(output, "mus_wg_andnc.bmu") {
-		t.Fatalf("expected verbose mapping output, got %q", output)
-	}
-}
-
 func TestTopdataConsoleSuppressesProgressInNormalMode(t *testing.T) {
 	var stdout bytes.Buffer
 	console := &topdataConsole{
@@ -348,77 +287,6 @@ func TestProjectConsoleEmitsRelativePaths(t *testing.T) {
 	}
 }

-func TestRunMusicScanUsesConfiguredDatasetsWithoutWriting(t *testing.T) {
-	root := t.TempDir()
-	mkdirAll(t, filepath.Join(root, "assets", "audio", "westgate"))
-	mkdirAll(t, filepath.Join(root, "build"))
-	writeFile(t, filepath.Join(root, "nwn-tool.yaml"), `
-module:
-  name: Test Module
-  resref: testmod
-paths:
-  assets: assets
-  build: build
-music:
-  datasets:
-    westgate_audio:
-      source: audio/westgate
-      output: generated/music
-      prefix: wg_
-`)
-	writeFile(t, filepath.Join(root, "assets", "audio", "westgate", "Theme Song.mp3"), "source-mp3")
-
-	ctx := context{
-		stdout: &bytes.Buffer{},
-		stderr: &bytes.Buffer{},
-		cwd:    root,
-		args:   []string{"music", "scan", "--dataset", "westgate_audio"},
-	}
-
-	if err := runMusic(ctx); err != nil {
-		t.Fatalf("runMusic failed: %v", err)
-	}
-	if _, err := os.Stat(filepath.Join(root, ".cache", "credits")); !os.IsNotExist(err) {
-		t.Fatalf("music scan should not write credits artifacts, stat err=%v", err)
-	}
-}
-
-func TestRunMusicListDatasets(t *testing.T) {
-	root := t.TempDir()
-	mkdirAll(t, filepath.Join(root, "assets"))
-	mkdirAll(t, filepath.Join(root, "build"))
-	writeFile(t, filepath.Join(root, "nwn-tool.yaml"), `
-module:
-  name: Test Module
-  resref: testmod
-paths:
-  assets: assets
-music:
-  datasets:
-    westgate_audio:
-      source: audio/westgate
-      output: generated/music
-      prefix: wg_
-`)
-
-	var stdout bytes.Buffer
-	ctx := context{
-		stdout: &stdout,
-		stderr: &bytes.Buffer{},
-		cwd:    root,
-		args:   []string{"music", "list-datasets"},
-	}
-
-	if err := runMusic(ctx); err != nil {
-		t.Fatalf("runMusic failed: %v", err)
-	}
-	for _, value := range []string{"westgate_audio", "audio/westgate", "generated/music", "wg_"} {
-		if !strings.Contains(stdout.String(), value) {
-			t.Errorf("dataset list missing configured value %q: %q", value, stdout.String())
-		}
-	}
-}
-
 func TestRunConfigEffectiveJSONShowsDefaultsAndProvenance(t *testing.T) {
 	root := t.TempDir()
 	writeFile(t, filepath.Join(root, "nwn-tool.yaml"), `
@@ -539,9 +407,6 @@ func TestInlineFlagParsersRejectEmptyValues(t *testing.T) {
 	if _, err := parseBuildHAKArgs([]string{"--hak="}); err == nil {
 		t.Fatalf("expected empty --hak inline value error, got %v", err)
 	}
-	if _, err := parseMusicCommandArgs([]string{"--dataset="}); err == nil {
-		t.Fatalf("expected empty --dataset inline value error, got %v", err)
-	}
 	if _, err := parseDeployWikiArgs("deploy-wiki", []string{"--endpoint="}); err == nil {
 		t.Fatalf("expected empty --endpoint inline value error, got %v", err)
 	}