Module manager: overridable manifest source + stronger install verification (#618)

# Description

Adds the ability to temporarily point the module manager at an alternate
manifest (registry) — via a one-shot CLI switch or an interactive command —
primarily for local testing of modules and registries. Also hardens module
installation so a download is always verified against the checksum declared in
the manifest, and makes a non-default manifest impossible to miss while working
interactively.

## Changes

### 1. Temporary manifest override

- **Global `--manifest <path|url>` switch** for one-shot commands
  (`internal/modmanager/modmanager.go`):
  - Accepts an `http(s)` URL **or** a local filesystem path (a `file://`
    prefix is also accepted), enabling fully local testing.
  - May appear anywhere in the command; it is stripped from args before
    subcommand dispatch (`applyManifestFlag`).
  - Supports both `--manifest x.yaml` and `--manifest=x.yaml` forms.
  - **Validates** that the source ends in `.yaml`/`.yml` (URL query/fragment
    ignored); otherwise errors out (`validateManifestSource`).
  - **Warns** whenever a non-default manifest is in use.
- **Manifest loading now supports local files** (`internal/modmanager/registry.go`):
  - `fetchRegistry` reads from a local path / `file://` or fetches over
    `http(s)` based on the configured source.
  - New `manifestSource` package variable holds the active source (defaults to
    the official registry URL).

### 2. Stronger install verification

`internal/modmanager/install.go`:

- **Refuses to install** a manifest entry that has no `sha256` checksum
  ("refusing to install unverifiable module") instead of failing with a
  confusing mismatch.
- The downloaded archive is streamed through `verifyArchive`, which fails with
  a clear `SHA256 mismatch` error when the bytes don't match the manifest. On
  failure no module directory is created.
- Adds a visible `Verified SHA256 checksum.` step on success.
- Module archives referenced by a manifest `url` may now be **local paths or
  `file://` URLs** (`openArchiveReader`), so a module can be installed entirely
  from local files for testing — still SHA256-verified.

### 3. Interactive `manifest-source` command

`internal/modmanager/interactive.go`:

- New REPL command `manifest-source` (alias `manifest`) — the interactive
  context can't use the `--manifest` switch, so this changes the source for the
  rest of the session:
  - no argument → prints the current source,
  - `<path|url>` → validates (`.yaml`), sets it, and warns,
  - `default` / `reset` → restores the default registry.
- Added to the interactive help listing.

### 4. Persistent visual warning for a non-default manifest

- When the active manifest differs from the default registry, a
  **color-emphasized banner** (bold black on a yellow background) is printed
  **above the prompt on every interactive iteration**, so the non-default state
  stays visible the whole session (`printCustomManifestBanner`,
  `warnBanner` in `internal/modmanager/color.go`). The banner disappears once
  the source is reset to default.

### 5. Tests & docs

- `internal/modmanager/modmanager_test.go`: added coverage for
  `validateManifestSource`, `applyManifestFlag` (and error paths),
  `handleManifestSourceCommand` (show/set/reset/invalid), local-file
  `fetchRegistry`, `isHTTPURL`, and `openArchiveReader` (local file + missing).
- `modules/README.md`: documented the `--manifest` switch, local-path/`file://`
  support, the interactive `manifest-source` command, and that downloads are
  SHA256-verified in all cases.

## Notes

- The override is **temporary** by design: the `--manifest` switch affects a
  single command, and the interactive `manifest-source` command affects only
  the current session. Nothing is persisted to disk.

Author: Volte6

internal/modmanager/color.go

@@ -68,6 +68,12 @@ func header(title string) string {
 	return cyan(title)
 }
 
+// warnBanner renders an attention-grabbing warning (bold black text on a yellow
+// background) so a non-default state stays visible.
+func warnBanner(s string) string {
+	return col("\033[1;30;43m", " "+s+" ")
+}
+
 // codeSnippet renders a shell command in a distinct style.
 func codeSnippet(s string) string {
 	return col(ansiGray, "  "+s)

internal/modmanager/install.go

@@ -7,7 +7,6 @@ import (
 	"compress/gzip"
 	"fmt"
 	"io"
-	"net/http"
 	"os"
 	"path/filepath"
 	"strings"
@@ -51,6 +50,13 @@ func cmdInstall(name string) error {
 		}
 	}
 
+	// A manifest entry must declare a checksum so the downloaded archive can be
+	// verified against it. Refuse to install otherwise rather than fetching
+	// unverifiable code.
+	if strings.TrimSpace(entry.SHA256) == "" {
+		return fmt.Errorf("manifest entry for %q has no sha256 checksum; refusing to install unverifiable module", name)
+	}
+
 	printStep("Downloading %s %s...", bold(entry.Name), cyan("v"+entry.Version))
 
 	tmpFile, err := os.CreateTemp("", "gomud-module-*.tmp")
@@ -63,24 +69,24 @@ func cmdInstall(name string) error {
 		os.Remove(tmpPath)
 	}()
 
-	resp, err := http.Get(entry.URL)
+	rc, err := openArchiveReader(entry.URL)
 	if err != nil {
-		return fmt.Errorf("downloading archive: %w", err)
-	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode != http.StatusOK {
-		return fmt.Errorf("downloading archive: HTTP %d from %s", resp.StatusCode, entry.URL)
+		return err
 	}
+	defer rc.Close()
 
-	if err := verifyArchive(resp.Body, tmpFile, entry.SHA256); err != nil {
+	// verifyArchive streams the download to disk while computing its SHA256 and
+	// fails if it does not match the checksum declared in the manifest.
+	if err := verifyArchive(rc, tmpFile, entry.SHA256); err != nil {
 		return err
 	}
 
 	if err := tmpFile.Close(); err != nil {
 		return fmt.Errorf("flushing temp file: %w", err)
 	}
 
+	printStep("Verified SHA256 checksum.")
+
 	destDir := filepath.Join("modules", name)
 	if _, err := os.Stat(destDir); err == nil {
 		fmt.Printf("%s Removing existing %s...\n", yellow("-"), gray(destDir))

internal/modmanager/interactive.go

@@ -19,6 +19,7 @@ func runInteractive() {
 
 	scanner := bufio.NewScanner(os.Stdin)
 	for {
+		printCustomManifestBanner()
 		fmt.Print(cyan(">") + " ")
 		if !scanner.Scan() {
 			// EOF (Ctrl-D)
@@ -92,6 +93,9 @@ func runInteractive() {
 				printError("%v", err)
 			}
 
+		case "manifest-source", "manifest":
+			handleManifestSourceCommand(args)
+
 		default:
 			printError("unknown command: %q (type 'help' for a list)", cmd)
 		}
@@ -103,6 +107,48 @@ func isInteractiveTerminal() bool {
 	return term.IsTerminal(int(os.Stdin.Fd()))
 }
 
+// handleManifestSourceCommand implements the interactive "manifest-source"
+// command. With no argument it prints the current manifest source. With
+// "default" (or "reset") it restores the default registry. Otherwise it points
+// the manager at the given .yaml file or URL for the rest of the session.
+func handleManifestSourceCommand(args []string) {
+	if len(args) == 0 {
+		printCurrentManifestSource()
+		return
+	}
+
+	if args[0] == "default" || args[0] == "reset" {
+		manifestSource = registryURL
+		printSuccess("Manifest source reset to the default registry.")
+		return
+	}
+
+	if err := useManifestOverride(args[0]); err != nil {
+		printError("%v", err)
+	}
+}
+
+// printCustomManifestBanner prints a prominent, color-emphasized warning above
+// the prompt whenever a non-default manifest source is active, so it stays
+// visible on every menu of the interactive session.
+func printCustomManifestBanner() {
+	if manifestSource == registryURL {
+		return
+	}
+	fmt.Println(warnBanner("⚠ CUSTOM MANIFEST SOURCE — not the default registry") +
+		" " + yellow(manifestSource))
+}
+
+// printCurrentManifestSource reports where the manifest is currently loaded from.
+func printCurrentManifestSource() {
+	if manifestSource == registryURL {
+		fmt.Println(gray("Manifest source: ") + dimStr("default registry"))
+		fmt.Println("  " + gray(registryURL))
+		return
+	}
+	fmt.Println(gray("Manifest source: ") + bold(manifestSource))
+}
+
 func printInteractiveHelp() {
 	fmt.Println()
 	fmt.Println(bold("Commands:"))
@@ -115,6 +161,7 @@ func printInteractiveHelp() {
 		{green("remove") + " <name>", "Remove an installed module"},
 		{green("update") + " [name]", "Check for updates; update a specific module if name given"},
 		{green("package") + " <name>", "Package a local module into a .tar.gz and print its SHA256"},
+		{green("manifest-source") + " [src]", "Show, or set for this session, the manifest source (.yaml file or URL; 'default' to reset)"},
 		{green("help"), "Show this help"},
 		{green("quit") + " / " + green("exit"), "Exit the module manager"},
 	}

internal/modmanager/modmanager.go

@@ -6,13 +6,19 @@ import (
 	"fmt"
 	"os"
 	"regexp"
+	"strings"
 )
 
 var validName = regexp.MustCompile(`^[a-z][a-z0-9-]*$`)
 
 // Run is the entry point for the module manager subcommand. args should be
 // os.Args[2:] (everything after "module").
 func Run(args []string) {
+	args, err := applyManifestFlag(args)
+	if err != nil {
+		fatalf("%v\n", err)
+	}
+
 	if len(args) == 0 {
 		if isInteractiveTerminal() {
 			runInteractive()
@@ -22,7 +28,6 @@ func Run(args []string) {
 		os.Exit(0)
 	}
 
-	var err error
 	switch args[0] {
 	case "list":
 		err = cmdList()
@@ -83,6 +88,69 @@ func fatalf(format string, args ...any) {
 	os.Exit(1)
 }
 
+// applyManifestFlag scans args for a global --manifest <source> (or
+// --manifest=<source>) flag, applies it as the manifest override, and returns
+// args with the flag and its value removed so subcommand parsing is unaffected.
+// The flag may appear anywhere in args.
+func applyManifestFlag(args []string) ([]string, error) {
+	var rest []string
+	for i := 0; i < len(args); i++ {
+		a := args[i]
+		switch {
+		case a == "--manifest":
+			if i+1 >= len(args) {
+				return nil, fmt.Errorf("--manifest requires a file path or URL")
+			}
+			if err := useManifestOverride(args[i+1]); err != nil {
+				return nil, err
+			}
+			i++ // skip the value we just consumed
+		case strings.HasPrefix(a, "--manifest="):
+			if err := useManifestOverride(strings.TrimPrefix(a, "--manifest=")); err != nil {
+				return nil, err
+			}
+		default:
+			rest = append(rest, a)
+		}
+	}
+	return rest, nil
+}
+
+// useManifestOverride validates source, points the module manager at it for the
+// remainder of this invocation, and warns the user that the default registry is
+// being overridden.
+func useManifestOverride(source string) error {
+	if err := validateManifestSource(source); err != nil {
+		return err
+	}
+	manifestSource = source
+	printManifestOverrideWarning(source)
+	return nil
+}
+
+// validateManifestSource ensures a custom manifest location points at a YAML
+// file. Both http(s) URLs and local filesystem paths are accepted, as long as
+// they end in .yaml or .yml (any query string or fragment on a URL is ignored).
+func validateManifestSource(source string) error {
+	if strings.TrimSpace(source) == "" {
+		return fmt.Errorf("--manifest requires a file path or URL")
+	}
+	lower := strings.ToLower(source)
+	if i := strings.IndexAny(lower, "?#"); i >= 0 {
+		lower = lower[:i]
+	}
+	if !strings.HasSuffix(lower, ".yaml") && !strings.HasSuffix(lower, ".yml") {
+		return fmt.Errorf("manifest must be a .yaml file, got %q", source)
+	}
+	return nil
+}
+
+// printManifestOverrideWarning warns that a non-default manifest is in use.
+func printManifestOverrideWarning(source string) {
+	printWarning("using a custom module manifest instead of the default registry: %s", bold(source))
+	fmt.Fprintln(os.Stderr, gray("         only use manifests from sources you trust; downloads are still SHA256-verified."))
+}
+
 func printUsage() {
 	fmt.Println()
 	fmt.Println(cyan("GoMud Module Manager"))
@@ -105,6 +173,12 @@ func printUsage() {
 		fmt.Printf("  %s  %s\n", padRight(e.cmd, 22), e.desc)
 	}
 	fmt.Println()
+	fmt.Println(bold("Global options:"))
+	fmt.Printf("  %s  %s\n", padRight(green("--manifest")+" <path|url>", 22),
+		"Temporarily use an alternate module manifest (.yaml file or")
+	fmt.Printf("  %s  %s\n", padRight("", 22),
+		"local path) instead of the default registry; for local testing")
+	fmt.Println()
 	fmt.Println(gray("Run without arguments (with a terminal) to start interactive mode."))
 	fmt.Println()
 	fmt.Println(bold("After installing or removing a module, rebuild the server:"))