Merge pull request #28 from miguelmartens/feat/brave-beta

Enhance Brave Browser support and documentation

Author: miguelmartens

README.md

@@ -12,7 +12,7 @@ Inspired by [SlimBrave](https://github.com/ltx0101/SlimBrave), [Debloat Brave Br
 
 - **macOS** only today (uses `defaults` and `~/Library/Preferences/com.brave.Browser.plist`)
 - **Go 1.25.6+** to build
-- **Brave Browser** installed in `/Applications/Brave Browser.app` (tested with Brave stable; policy keys may vary by Brave version)
+- **Brave Browser** installed in `/Applications/Brave Browser.app` (or **Brave Browser Beta** in `/Applications/Brave Browser Beta.app` with `--beta`; policy keys may vary by Brave version)
 
 **Platform support:** Cowardly currently supports **macOS only**. Support for **Linux** and **Windows** may be added in the future; on those platforms Brave uses different policy mechanisms (e.g. JSON on Linux, registry/Group Policy on Windows). See **[docs/PLATFORMS.md](docs/PLATFORMS.md)** for details and contribution notes.
 
@@ -147,6 +147,14 @@ After applying or resetting, **restart Brave Browser** for changes to take effec
   cowardly -r
   ```
 
+- **Target Brave Browser Beta** — Use `--beta` with any command to manage Brave Beta instead of stable:
+
+  ```bash
+  cowardly --beta --apply
+  cowardly --beta --reset
+  cowardly --beta
+  ```
+
 - **Print current settings** (user and enforced/managed when present)
 
   ```bash

cmd/cowardly/main.go

@@ -25,6 +25,12 @@ func main() {
 	}
 
 	args := os.Args[1:]
+	for _, arg := range args {
+		if strings.TrimLeft(arg, "-") == "beta" {
+			brave.UseBeta(true)
+			break
+		}
+	}
 	for _, arg := range args {
 		arg = strings.TrimLeft(arg, "-")
 		switch {
@@ -91,7 +97,11 @@ func main() {
 	}
 
 	if !brave.BraveInstalled() {
-		fmt.Fprintln(os.Stderr, "Brave Browser not found in /Applications. Install Brave first.")
+		which := "Brave Browser"
+		if brave.IsBeta() {
+			which = "Brave Browser Beta"
+		}
+		fmt.Fprintf(os.Stderr, "%s not found in /Applications. Install Brave first.\n", which)
 		os.Exit(1)
 	}
 
@@ -104,10 +114,14 @@ func main() {
 
 func versionInfo() {
 	fmt.Printf("Cowardly version: %s\n", Version)
+	which := "Brave"
+	if brave.IsBeta() {
+		which = "Brave Beta"
+	}
 	if v := brave.BraveVersion(); v != "" {
-		fmt.Printf("Brave version: %s\n", v)
+		fmt.Printf("%s version: %s\n", which, v)
 	} else {
-		fmt.Println("Brave version: (not installed or unknown)")
+		fmt.Printf("%s version: (not installed or unknown)\n", which)
 	}
 }
 
@@ -206,7 +220,11 @@ func applyPrivacyGuides(basePresetID string) {
 		basePresetID = presets.PrivacyGuidesBasePresetID
 	}
 	if !brave.BraveInstalled() {
-		fmt.Fprintln(os.Stderr, "Brave Browser not found in /Applications.")
+		which := "Brave Browser"
+		if brave.IsBeta() {
+			which = "Brave Browser Beta"
+		}
+		fmt.Fprintf(os.Stderr, "%s not found in /Applications.\n", which)
 		os.Exit(1)
 	}
 	if brave.BraveRunning() {
@@ -238,7 +256,11 @@ func applyPrivacyGuides(basePresetID string) {
 
 func applyPreset(presetID string) {
 	if !brave.BraveInstalled() {
-		fmt.Fprintln(os.Stderr, "Brave Browser not found in /Applications.")
+		which := "Brave Browser"
+		if brave.IsBeta() {
+			which = "Brave Browser Beta"
+		}
+		fmt.Fprintf(os.Stderr, "%s not found in /Applications.\n", which)
 		os.Exit(1)
 	}
 	if brave.BraveRunning() {
@@ -269,7 +291,11 @@ func applyPreset(presetID string) {
 
 func applyFile(path string) {
 	if !brave.BraveInstalled() {
-		fmt.Fprintln(os.Stderr, "Brave Browser not found in /Applications.")
+		which := "Brave Browser"
+		if brave.IsBeta() {
+			which = "Brave Browser Beta"
+		}
+		fmt.Fprintf(os.Stderr, "%s not found in /Applications.\n", which)
 		os.Exit(1)
 	}
 	if brave.BraveRunning() {
@@ -437,7 +463,11 @@ func deleteBackup(path string) {
 
 func reapply() {
 	if !brave.BraveInstalled() {
-		fmt.Fprintln(os.Stderr, "Brave Browser not found in /Applications.")
+		which := "Brave Browser"
+		if brave.IsBeta() {
+			which = "Brave Browser Beta"
+		}
+		fmt.Fprintf(os.Stderr, "%s not found in /Applications.\n", which)
 		os.Exit(1)
 	}
 	if brave.BraveRunning() {
@@ -494,7 +524,16 @@ func installLoginHook() {
 	if err != nil {
 		cowardlyPath = "cowardly" // fallback to PATH
 	}
+	reapplyArgs := []string{"--reapply"}
+	if brave.IsBeta() {
+		reapplyArgs = []string{"--beta", "--reapply"}
+	}
 	plistPath := filepath.Join(launchAgentDir, "com.cowardly.reapply.plist")
+	programArgs := append([]string{cowardlyPath}, reapplyArgs...)
+	programArgsXML := ""
+	for _, a := range programArgs {
+		programArgsXML += fmt.Sprintf("    <string>%s</string>\n", escapePlistString(a))
+	}
 	plist := fmt.Sprintf(`<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -503,9 +542,7 @@ func installLoginHook() {
   <string>com.cowardly.reapply</string>
   <key>ProgramArguments</key>
   <array>
-    <string>%s</string>
-    <string>--reapply</string>
-  </array>
+%s  </array>
   <key>RunAtLoad</key>
   <true/>
   <key>StandardErrorPath</key>
@@ -514,7 +551,7 @@ func installLoginHook() {
   <string>%s/reapply.log</string>
 </dict>
 </plist>
-`, cowardlyPath, dir, dir)
+`, programArgsXML, dir, dir)
 	if err := os.WriteFile(plistPath, []byte(plist), 0644); err != nil {
 		fmt.Fprintf(os.Stderr, "install-login-hook: %v\n", err)
 		os.Exit(1)
@@ -524,6 +561,16 @@ func installLoginHook() {
 	fmt.Println("To remove: rm", plistPath)
 }
 
+// escapePlistString escapes a string for use inside a plist <string> element.
+func escapePlistString(s string) string {
+	s = strings.ReplaceAll(s, "&", "&amp;")
+	s = strings.ReplaceAll(s, "<", "&lt;")
+	s = strings.ReplaceAll(s, ">", "&gt;")
+	s = strings.ReplaceAll(s, "\"", "&quot;")
+	s = strings.ReplaceAll(s, "'", "&apos;")
+	return s
+}
+
 // resolveBackupPath returns the full path if path is a filename matching a backup, or path if it's already a full path that exists.
 func resolveBackupPath(path string) string {
 	path = strings.TrimSpace(path)
@@ -551,6 +598,7 @@ func printUsage() {
 
 Usage:
   cowardly                        Start the TUI
+  cowardly --beta                 Target Brave Browser Beta (use with any command)
   cowardly --apply, -a             Apply Quick Debloat preset and exit
   cowardly --apply=<id>            Apply preset by ID (e.g. quick, max-privacy)
   cowardly --privacy-guides [=base] Apply Privacy Guides supplement (default base: quick)
@@ -568,5 +616,5 @@ Usage:
   cowardly --delete-backup=<path>  Delete a backup file
   cowardly --help, -h              Show this help
 
-Restart Brave Browser after applying or resetting settings.`)
+Use --beta to target Brave Browser Beta instead of stable. Restart Brave after applying or resetting settings.`)
 }

docs/FEATURES.md

@@ -5,7 +5,7 @@ This document summarizes what Cowardly currently does. For possible future work,
 ## Core: policy application
 
 - **Apply settings** — Write Brave policy keys (bool, integer, string) to macOS. Used by presets and Custom mode.
-- **Managed preferences first** — Tries to write to `/Library/Managed Preferences/com.brave.Browser.plist` so Brave enforces policies (Rewards, Wallet, etc. hidden). Falls back to user preferences (`~/Library/Preferences/com.brave.Browser.plist`) if the user cancels the auth dialog or lacks admin rights.
+- **Managed preferences first** — Tries to write to `/Library/Managed Preferences/com.brave.Browser.plist` (or `com.brave.Browser.beta.plist` with `--beta`) so Brave enforces policies (Rewards, Wallet, etc. hidden). Falls back to user preferences (`~/Library/Preferences/com.brave.Browser.plist` or `com.brave.Browser.beta.plist`) if the user cancels the auth dialog or lacks admin rights.
 - **Raw XML plist for managed** — Managed plist is generated as valid XML (not via `defaults write`) and copied into place with correct ownership and permissions.
 - **Administrator privileges via AppleScript** — macOS authentication dialog (password or Touch ID) for writing to managed preferences; no password in the terminal.
 - **Reset** — Removes all Brave policy settings: deletes user plist keys (and the plist file when empty) and removes the managed plist when present. Returns whether a managed plist existed and whether it was removed. Reset is blocked if Brave is running (user is told to quit Brave first).
@@ -37,6 +37,7 @@ See [POLICY-ENFORCEMENT.md](POLICY-ENFORCEMENT.md) for the rationale and impleme
 
 | Feature            | Flags                                                                                                                                                 |
 | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Brave Beta         | `--beta` — target Brave Browser Beta instead of stable (use with any command)                                                                         |
 | Apply preset       | `--apply`, `-a`, `--apply=<id>` (e.g. `max-privacy`, `balanced`)                                                                                      |
 | Privacy Guides     | `--privacy-guides` (base from config or quick), `--privacy-guides=<base>` (e.g. max-privacy, custom)                                                  |
 | Apply from file    | `--apply-file=<path>` (YAML with same `settings` format as presets)                                                                                   |

docs/INSTALL.md

@@ -5,7 +5,7 @@ This guide covers installing Cowardly from a **release archive** (no Go or repo
 ## Prerequisites
 
 - **macOS** (Intel or Apple Silicon)
-- **Brave Browser** installed at `/Applications/Brave Browser.app`
+- **Brave Browser** installed at `/Applications/Brave Browser.app` (or Brave Beta at `/Applications/Brave Browser Beta.app`; use `--beta` to target it)
 
 ## Install with Homebrew
 

docs/POLICY-ENFORCEMENT.md

@@ -8,8 +8,8 @@ Brave (like Chromium) supports policy keys that disable features such as Rewards
 
 | Location                | Path                                                   | Enforced?                                                                  |
 | ----------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------- |
-| **User preferences**    | `~/Library/Preferences/com.brave.Browser.plist`        | **No** — Brave may still show Rewards, Wallet, etc.                        |
-| **Managed preferences** | `/Library/Managed Preferences/com.brave.Browser.plist` | **Yes** — Brave treats these as mandatory and hides/ disables the features |
+| **User preferences**    | `~/Library/Preferences/com.brave.Browser.plist` (or `.beta` with `--beta`)        | **No** — Brave may still show Rewards, Wallet, etc.                        |
+| **Managed preferences** | `/Library/Managed Preferences/com.brave.Browser.plist` (or `.beta` with `--beta`)   | **Yes** — Brave treats these as mandatory and hides/ disables the features |
 
 If you only run `defaults write com.brave.Browser BraveRewardsDisabled -bool true`, the key is written to the user plist. After restarting Brave, the UI can still show Rewards and Wallet. To get **enforced** behavior (features hidden/disabled), the same keys must be present in the **managed** plist under `/Library/Managed Preferences/`. That path is the standard macOS location for mandatory (MDM-style) policies.
 

internal/brave/preferences.go

@@ -31,12 +31,7 @@ const plistXMLFooter = `
 </plist>
 `
 
-const (
-	// Domain is the macOS defaults domain for Brave Browser (user preferences).
-	Domain = "com.brave.Browser"
-	// ManagedPreferencesPath is the system path for mandatory policies (Brave enforces these and hides Rewards/Wallet etc.).
-	ManagedPreferencesPath = "/Library/Managed Preferences/com.brave.Browser"
-)
+// Domain and ManagedPreferencesPath are now functions; see variant.go.
 
 // ValueType is the plist value type for a preference.
 type ValueType string
@@ -153,7 +148,7 @@ func writeToPath(path string, s Setting) error {
 
 // Write applies a single setting to user preferences using `defaults write`.
 func Write(s Setting) error {
-	return writeToPath(Domain, s)
+	return writeToPath(Domain(), s)
 }
 
 // WriteAll applies multiple settings to user preferences; stops on first error.
@@ -191,7 +186,7 @@ func WriteAllToManaged(settings []Setting) error {
 	}
 	defer func() { _ = os.RemoveAll(tmpDir) }()
 
-	src := filepath.Join(tmpDir, "com.brave.Browser.plist")
+	src := filepath.Join(tmpDir, Domain()+".plist")
 	xmlContent := settingsToPlistXML(settings)
 	if err := os.WriteFile(src, []byte(xmlContent), 0600); err != nil {
 		return fmt.Errorf("write temp plist: %w", err)
@@ -201,8 +196,9 @@ func WriteAllToManaged(settings []Setting) error {
 	// and never interpolated into the shell command, so there is no shell injection from presets.
 	// Use AppleScript "with administrator privileges" so a GUI dialog appears (password or Touch ID).
 	// chmod 644 so the plist is readable by Brave (per hi-one / managed preferences practice).
-	shellCmd := fmt.Sprintf("mkdir -p \"/Library/Managed Preferences\" && cp %s \"/Library/Managed Preferences/com.brave.Browser.plist\" && chown root:wheel \"/Library/Managed Preferences/com.brave.Browser.plist\" && chmod 644 \"/Library/Managed Preferences/com.brave.Browser.plist\"",
-		shellSingleQuoted(src))
+	managedPlist := shellSingleQuoted(ManagedPreferencesPath() + ".plist")
+	shellCmd := fmt.Sprintf("mkdir -p \"/Library/Managed Preferences\" && cp %s %s && chown root:wheel %s && chmod 644 %s",
+		shellSingleQuoted(src), managedPlist, managedPlist, managedPlist)
 	script := `do shell script "` + escapeForAppleScript(shellCmd) + `" with administrator privileges`
 	ctx, cancel := context.WithTimeout(context.Background(), osascriptTimeout)
 	defer cancel()
@@ -234,7 +230,7 @@ func Read(key string) (string, bool) {
 	}
 	ctx, cancel := context.WithTimeout(context.Background(), defaultsTimeout)
 	defer cancel()
-	cmd := exec.CommandContext(ctx, "defaults", "read", Domain, key)
+	cmd := exec.CommandContext(ctx, "defaults", "read", Domain(), key)
 	out, err := cmd.CombinedOutput()
 	if err != nil || ctx.Err() != nil {
 		return "", false
@@ -247,7 +243,7 @@ func ManagedPlistExists() bool {
 	if !IsMacOS() {
 		return false
 	}
-	_, err := os.Stat(ManagedPreferencesPath + ".plist")
+	_, err := os.Stat(ManagedPreferencesPath() + ".plist")
 	return err == nil
 }
 
@@ -259,7 +255,7 @@ func ReadManaged(key string) (string, bool) {
 	}
 	ctx, cancel := context.WithTimeout(context.Background(), defaultsTimeout)
 	defer cancel()
-	cmd := exec.CommandContext(ctx, "defaults", "read", ManagedPreferencesPath, key)
+	cmd := exec.CommandContext(ctx, "defaults", "read", ManagedPreferencesPath(), key)
 	out, err := cmd.CombinedOutput()
 	if err != nil || ctx.Err() != nil {
 		return "", false
@@ -274,7 +270,7 @@ func Delete(key string) error {
 	}
 	ctx, cancel := context.WithTimeout(context.Background(), defaultsTimeout)
 	defer cancel()
-	cmd := exec.CommandContext(ctx, "defaults", "delete", Domain, key)
+	cmd := exec.CommandContext(ctx, "defaults", "delete", Domain(), key)
 	_ = cmd.Run() // ignore error if key missing
 	return nil
 }
@@ -289,7 +285,7 @@ func Reset() (hadManaged, managedRemoved bool, err error) {
 	}
 	ctx, cancel := context.WithTimeout(context.Background(), defaultsTimeout)
 	defer cancel()
-	cmd := exec.CommandContext(ctx, "defaults", "delete", Domain)
+	cmd := exec.CommandContext(ctx, "defaults", "delete", Domain())
 	if out, runErr := cmd.CombinedOutput(); runErr != nil {
 		outStr := string(out)
 		// Domain already absent is fine (no user plist to delete).
@@ -303,7 +299,7 @@ func Reset() (hadManaged, managedRemoved bool, err error) {
 	if userPath, pathErr := UserPreferencesPath(); pathErr == nil {
 		_ = os.Remove(userPath)
 	}
-	managedPath := ManagedPreferencesPath + ".plist"
+	managedPath := ManagedPreferencesPath() + ".plist"
 	if _, statErr := os.Stat(managedPath); statErr == nil {
 		hadManaged = true
 		script := `do shell script "rm -f ` + escapeForAppleScript(shellSingleQuoted(managedPath)) + `" with administrator privileges`
@@ -317,15 +313,12 @@ func Reset() (hadManaged, managedRemoved bool, err error) {
 	return hadManaged, managedRemoved, nil
 }
 
-// BraveAppPath is the default path to the Brave Browser application.
-const BraveAppPath = "/Applications/Brave Browser.app"
-
-// BraveInstalled checks if Brave Browser is installed at BraveAppPath.
+// BraveInstalled checks if Brave Browser is installed at BraveAppPath().
 func BraveInstalled() bool {
 	if !IsMacOS() {
 		return false
 	}
-	info, err := os.Stat(BraveAppPath)
+	info, err := os.Stat(BraveAppPath())
 	return err == nil && info.IsDir()
 }
 
@@ -335,12 +328,12 @@ func BraveVersion() string {
 	if !IsMacOS() {
 		return ""
 	}
-	infoPlist := filepath.Join(BraveAppPath, "Contents", "Info.plist")
+	infoPlist := filepath.Join(BraveAppPath(), "Contents", "Info.plist")
 	if _, err := os.Stat(infoPlist); err != nil {
 		return ""
 	}
 	// defaults read expects the path without .plist extension
-	domain := filepath.Join(BraveAppPath, "Contents", "Info")
+	domain := filepath.Join(BraveAppPath(), "Contents", "Info")
 	ctx, cancel := context.WithTimeout(context.Background(), defaultsTimeout)
 	defer cancel()
 	cmd := exec.CommandContext(ctx, "defaults", "read", domain, "CFBundleShortVersionString")
@@ -359,7 +352,7 @@ func BraveRunning() bool {
 	}
 	ctx, cancel := context.WithTimeout(context.Background(), defaultsTimeout)
 	defer cancel()
-	cmd := exec.CommandContext(ctx, "pgrep", "-x", "Brave Browser")
+	cmd := exec.CommandContext(ctx, "pgrep", "-x", braveProcessName())
 	err := cmd.Run()
 	return err == nil
 }
@@ -373,7 +366,7 @@ func UserPreferencesPath() (string, error) {
 	if err != nil {
 		return "", fmt.Errorf("home dir: %w", err)
 	}
-	return filepath.Join(home, "Library", "Preferences", Domain+".plist"), nil
+	return filepath.Join(home, "Library", "Preferences", Domain()+".plist"), nil
 }
 
 // BackupDir returns the backups directory path (~/Library/Application Support/cowardly/backups).