Enhance branding and release workflows

- Updated README.md to include a reference to branding and releases documentation.
- Modified brand_config.py to support multi-brand packaging, including functions for collecting local release data and merging release manifests.
- Adjusted build_macos.sh to set a default brand if none is specified and updated DMG naming conventions.
- Enhanced create_release.ps1 and create_release.sh scripts to support dry-run functionality and improved artifact handling.
- Added a new template for brand configuration in build/brands/template.jsonc.
- Created comprehensive branding and releases documentation in docs/BRANDING_AND_RELEASES.md.
- Added unit tests for new branding functionalities in test_brand_config.py.

build/scripts/brand_config.py

@@ -60,6 +60,8 @@ DEFAULT_BRAND_VALUES: dict[str, Any] = {
     "license_rtf": "resources/license.rtf",
 }
 
+DEFAULT_BRAND_ID = str(DEFAULT_BRAND_VALUES["brand_id"])
+
 
 def project_root() -> Path:
     return Path(__file__).resolve().parents[2]
@@ -70,6 +72,18 @@ def brands_dir(root: Path | None = None) -> Path:
     return base / "build" / "brands"
 
 
+def available_brand_names(root: Path | None = None) -> list[str]:
+    """Return all supported brand names, including the default build."""
+    base = root or project_root()
+    names = [DEFAULT_BRAND_ID]
+    manifest_dir = brands_dir(base)
+    if manifest_dir.exists():
+        for manifest in sorted(manifest_dir.glob("*.json")):
+            if manifest.stem not in names:
+                names.append(manifest.stem)
+    return names
+
+
 def load_brand_config(
     brand: str | None = None,
     *,
@@ -80,7 +94,7 @@ def load_brand_config(
     base = root or project_root()
     values = dict(DEFAULT_BRAND_VALUES)
 
-    if manifest_path is None and brand:
+    if manifest_path is None and brand and brand != DEFAULT_BRAND_ID:
         manifest_path = brands_dir(base) / f"{brand}.json"
 
     if manifest_path and manifest_path.exists():
@@ -160,6 +174,92 @@ def generate_release_manifest(
     return output_path
 
 
+def merge_release_manifests(
+    base_manifest: dict[str, Any], overlay_manifest: dict[str, Any]
+) -> dict[str, Any]:
+    """Merge two release manifests, preserving previously uploaded platforms."""
+    merged: dict[str, Any] = {
+        "version": overlay_manifest.get("version") or base_manifest.get("version", ""),
+        "channel": overlay_manifest.get("channel") or base_manifest.get("channel", "stable"),
+        "brands": dict(base_manifest.get("brands", {})),
+    }
+
+    for brand_id, entries in overlay_manifest.get("brands", {}).items():
+        brand_entry = dict(merged["brands"].get(brand_id, {}))
+        for platform_key, platform_value in entries.items():
+            if platform_value:
+                brand_entry[platform_key] = platform_value
+        merged["brands"][brand_id] = brand_entry
+
+    return merged
+
+
+def collect_local_release_data(
+    version: str,
+    *,
+    platform: str,
+    root: Path | None = None,
+    brands: list[str] | None = None,
+) -> dict[str, Any]:
+    """Collect local artifacts and manifest entries for the requested platform."""
+    base = root or project_root()
+    selected_brands = brands or available_brand_names(base)
+    release_manifest: dict[str, Any] = {
+        "version": version,
+        "channel": "stable",
+        "brands": {},
+    }
+    artifacts: list[str] = []
+    found_brands: list[str] = []
+
+    for brand_name in selected_brands:
+        brand = load_brand_config(brand_name, root=base)
+        release_manifest["channel"] = brand.update_channel
+
+        if platform == "windows":
+            artifact_dir = base / "build" / "dist" / "windows" / brand.brand_id
+            installer = artifact_dir / brand.windows_installer_name(version)
+            checksum = artifact_dir / f"{installer.name}.sha256"
+            platform_key = "windows-x64"
+        elif platform == "macos":
+            artifact_dir = base / "build" / "dist" / "macos" / brand.brand_id
+            installer = artifact_dir / brand.macos_installer_name(version)
+            checksum = artifact_dir / f"{installer.name}.sha256"
+            platform_key = "macos-universal"
+
+            if not installer.exists() and brand.brand_id == DEFAULT_BRAND_ID:
+                legacy_installer = (base / "build" / "dist" / "macos") / brand.macos_installer_name(
+                    version
+                )
+                legacy_checksum = legacy_installer.parent / f"{legacy_installer.name}.sha256"
+                if legacy_installer.exists():
+                    installer = legacy_installer
+                    checksum = legacy_checksum
+        else:
+            raise ValueError(f"Unsupported platform: {platform}")
+
+        if not installer.exists():
+            continue
+
+        found_brands.append(brand.brand_id)
+        artifacts.append(str(installer))
+        if checksum.exists():
+            artifacts.append(str(checksum))
+
+        release_manifest["brands"].setdefault(brand.brand_id, {})[platform_key] = {
+            "installer": installer.name,
+            "checksum": checksum.name if checksum.exists() else "",
+        }
+
+    return {
+        "version": version,
+        "platform": platform,
+        "brands": found_brands,
+        "artifacts": artifacts,
+        "manifest": release_manifest,
+    }
+
+
 def cli_env(args: argparse.Namespace) -> int:
     brand = load_brand_config(args.brand)
     assignments = {
@@ -187,6 +287,26 @@ def cli_manifest(args: argparse.Namespace) -> int:
     return 0
 
 
+def cli_local_release_data(args: argparse.Namespace) -> int:
+    data = collect_local_release_data(
+        args.version,
+        platform=args.platform,
+        brands=args.brands,
+    )
+    print(json.dumps(data, indent=2))
+    return 0
+
+
+def cli_merge_manifests(args: argparse.Namespace) -> int:
+    base_manifest = json.loads(Path(args.base).read_text(encoding="utf-8"))
+    overlay_manifest = json.loads(Path(args.overlay).read_text(encoding="utf-8"))
+    merged = merge_release_manifests(base_manifest, overlay_manifest)
+    output_path = Path(args.output)
+    output_path.write_text(json.dumps(merged, indent=2), encoding="utf-8")
+    print(output_path)
+    return 0
+
+
 def cli_show(args: argparse.Namespace) -> int:
     brand = load_brand_config(args.brand)
     print(
@@ -224,6 +344,18 @@ def main() -> int:
     manifest_parser.add_argument("--brands", nargs="+", required=True)
     manifest_parser.set_defaults(func=cli_manifest)
 
+    local_parser = subparsers.add_parser("local-release-data")
+    local_parser.add_argument("--version", required=True)
+    local_parser.add_argument("--platform", choices=["windows", "macos"], required=True)
+    local_parser.add_argument("--brands", nargs="+")
+    local_parser.set_defaults(func=cli_local_release_data)
+
+    merge_parser = subparsers.add_parser("merge-manifests")
+    merge_parser.add_argument("--base", required=True)
+    merge_parser.add_argument("--overlay", required=True)
+    merge_parser.add_argument("--output", required=True)
+    merge_parser.set_defaults(func=cli_merge_manifests)
+
     show_parser = subparsers.add_parser("show")
     show_parser.add_argument("--brand", required=True)
     show_parser.set_defaults(func=cli_show)