dotbrave 0.1.0__tar.gz

dotbrave-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    name: pytest (${{ matrix.os }} / py${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install package + test extras
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[test]"
+
+      - name: Run pytest
+        run: pytest -q

dotbrave-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,50 @@
+name: Publish to PyPI
+
+# Triggered when you push a tag like `v0.2.0`. Workflow:
+#   1. tag locally       → git tag v0.2.0
+#   2. push the tag      → git push origin v0.2.0
+#   3. this workflow runs → builds sdist + wheel, validates, uploads
+#
+# Setup needed once before the first release:
+#   - Generate an API token at https://pypi.org/manage/account/token/
+#     (scope it to the dotbrave project after the first upload).
+#   - Add it as a GitHub Actions secret named `PYPI_API_TOKEN`
+#     (Settings → Secrets and variables → Actions → New repository secret).
+#
+# After dotbrave is published once, prefer migrating to PyPI Trusted
+# Publishing (OIDC, no shared secret) — see https://docs.pypi.org/trusted-publishers/
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  build-and-publish:
+    name: build + upload
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install build tooling
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+
+      - name: Build sdist + wheel
+        run: python -m build
+
+      - name: Validate metadata
+        run: twine check dist/*
+
+      - name: Upload to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: twine upload dist/*

dotbrave-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.env
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.tox/
+htmlcov/
+.coverage
+*.bak.*
+.worktrees/
+
+# nix
+result
+result-*

dotbrave-0.1.0/CLAUDE.md

@@ -0,0 +1,121 @@
+# CLAUDE.md
+
+Guidance for agents changing this repository. User-facing setup, examples,
+and CLI reference belong in `README.md` and runtime `--help`; keep this file
+focused on implementation constraints.
+
+## Project
+
+`dotbrave` manages Brave browser customizations from TOML files: managed
+tables `[shortcuts]`, `[settings]`, `[pwa]`, applied live when possible with
+an automatic offline fallback, on Linux/macOS/Windows across the stable,
+beta, and nightly channels. It is a Python 3.11+ stdlib-only CLI package,
+extracted from the multi-browser `xom11/dotbrowser` project. The CLI is
+single-browser: `dotbrave apply`, not `dotbrave brave apply`.
+
+## Commands
+
+Run from the repository root:
+
+```bash
+pip install -e ".[test]"
+PYTHONPATH=src python -m dotbrave --help
+PYTHONPATH=src python -m dotbrave apply --help
+pytest -q
+
+# Regenerate the command-name mapping from upstream brave-core headers.
+# Requires an authenticated `gh` CLI.
+python scripts/generate_brave_command_ids.py
+```
+
+Useful targeted suites:
+
+```bash
+pytest tests/test_help.py tests/test_smoke.py
+pytest tests/test_unified_apply.py tests/test_settings_apply.py tests/test_pwa_apply.py
+pytest tests/test_live_apply.py tests/test_brave_live.py tests/test_apply_live.py
+pytest tests/test_export.py tests/test_restore.py tests/test_brave_channel.py
+pytest tests/test_platform.py tests/test_macos_pwa_daemon.py
+```
+
+## Code Map
+
+- `src/dotbrave/cli.py`: root parser; mounts actions via
+  `browser.register(parser)`.
+- `src/dotbrave/browser.py`: channel/profile-root resolution, plan
+  assembly, init template, `cmd_*` handlers, registration.
+- `src/dotbrave/shortcuts.py`, `settings.py`, `pwa.py`: namespace wrappers
+  (module-level state kept patchable for tests).
+- `src/dotbrave/live.py`: Brave live-apply routes (settingsPrivate, New
+  Tab actions, CommandsService).
+- `src/dotbrave/utils.py`: Brave `BrowserProcess` config per channel.
+- `src/dotbrave/command_ids.py`: generated name<->id mapping.
+- `src/dotbrave/_base/`: engine shared with upstream dotbrowser:
+  `orchestrator.py` (config loading, unified apply/init/export/restore,
+  argparse wiring), `utils.py` (`Plan`, atomic write), `settings.py`
+  (dotted keys + MAC refusal), `pwa.py` (policy storage + macOS daemon),
+  `process.py`, `cdp.py`, `live_apply.py`.
+- `examples/*.toml`: valid user-facing config samples.
+- `tests/`: behavior contracts. Add or update tests alongside behavior or
+  CLI-help changes.
+
+## Invariants
+
+Preserve these contracts unless a change explicitly redesigns them:
+
+1. `apply` uses module `Plan` objects and one orchestrated cycle. Validate
+   all selected namespaces before committing profile changes; create at most
+   one Preferences backup per offline apply.
+2. Missing TOML table means "skip this namespace"; an empty table means
+   "remove/reset entries previously managed by dotbrave".
+3. `[settings]` must refuse MAC-protected keys found in either `Preferences`
+   or sibling `Secure Preferences`. Never make a write that Brave will
+   silently reset on launch.
+4. `[pwa]` is external managed policy storage. It requires sudo on
+   Linux/macOS or Administrator on Windows when changed, writes before the
+   Preferences commit, and has no Preferences sidecar.
+   On macOS the policy file is kept alive by a root-owned self-healing
+   LaunchDaemon (`org.dotbrave.<bundle>.pwa`) installed during the same
+   privileged write; an empty `[pwa]` table removes the daemon and its
+   support files. Keep `build_heal_script`/`build_launchd_plist` pure and
+   `install_self_healing_daemon`/`remove_self_healing_daemon` patchable.
+5. Plain `apply` manages live apply. Endpoints bind to `127.0.0.1` and
+   remain internal; no public endpoint or force-kill switch is exposed.
+   Unsupported live settings and removals fall back to a normal close,
+   verified offline apply, and relaunch. A diff whose only changes are
+   `[pwa]` never touches the running browser: the policy is written
+   directly (no endpoint bootstrap) and Brave loads it at next launch.
+6. `export` intentionally omits `[settings]` (Chromium has no defaults
+   table for arbitrary prefs). It emits `[shortcuts]` diffs against
+   `brave.default_accelerators` plus `[pwa]`.
+7. `restore` restores Preferences backups and clears shortcut/settings
+   sidecars. If Brave is running, it closes normally and restarts; it does
+   not roll back external `[pwa]` policy.
+8. Profile flags (`--channel`, `-r`, `-p`) are accepted both before and
+   after the action name: real defaults live on the root parser; action
+   parsers re-declare them with `argparse.SUPPRESS` so the after-action
+   form overrides. Profile-reading leaves set `_needs_profile` so
+   `_normalize_brave_args` skips profile-root resolution for `init` and
+   `shortcuts list`. Keep new action parsers consistent with this scheme.
+9. Runtime help is part of the capability contract. Do not reintroduce
+   manual endpoint-selection or force-kill controls.
+
+## Browser Notes
+
+- Shortcut values use Chromium KeyEvent-style bindings. `Meta+` and
+  `Command+` are normalized per platform before persistence.
+- `--channel` changes both profile discovery and process handling.
+  Non-stable Linux channels require PID filtering so applying Beta/Nightly
+  does not close another Brave channel.
+- Keep shared engine logic in `_base/` (it mirrors upstream dotbrowser's
+  `_base/`, which eases porting fixes across the two repos); Brave-specific
+  behavior belongs in the top-level modules.
+- Preserve testability: policy paths, privilege writers, and process
+  callbacks are intentionally patchable in tests.
+
+## Release
+
+`src/dotbrave/__init__.py::__version__` is the version source of truth;
+`pyproject.toml` reads it through Hatch. Releases are tag-driven through
+`.github/workflows/release.yml` after tests pass (needs the
+`PYPI_API_TOKEN` repo secret).

dotbrave-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xom11
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OF OTHER DEALINGS IN THE
+SOFTWARE.

dotbrave-0.1.0/PKG-INFO

@@ -0,0 +1,277 @@
+Metadata-Version: 2.4
+Name: dotbrave
+Version: 0.1.0
+Summary: Manage Brave as a dotfile: keyboard shortcuts, general settings (non-MAC keys), and force-installed PWAs from one TOML.
+Project-URL: Homepage, https://github.com/xom11/dotbrave
+Project-URL: Issues, https://github.com/xom11/dotbrave/issues
+Author: xom11
+License: MIT
+License-File: LICENSE
+Keywords: brave,browser,config,dotfiles,keybindings,pwa,settings,shortcuts
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# dotbrave
+
+[![CI](https://github.com/xom11/dotbrave/actions/workflows/ci.yml/badge.svg)](https://github.com/xom11/dotbrave/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/dotbrave.svg)](https://pypi.org/project/dotbrave/)
+[![Python](https://img.shields.io/pypi/pyversions/dotbrave.svg)](https://pypi.org/project/dotbrave/)
+
+Manage Brave as a dotfile. Keep keyboard shortcuts, UI tweaks, and
+force-installed web apps in a single TOML, apply with one command, sync
+across machines — no Brave Sync required.
+
+> **Status: alpha.** Works on Linux, macOS, and Windows against Brave
+> stable, beta, and nightly. Extracted from the multi-browser
+> [dotbrowser](https://github.com/xom11/dotbrowser) project as a focused,
+> Brave-only tool with a flatter CLI (`dotbrave apply` instead of
+> `dotbrowser brave apply`). Python 3.11+, standard library only.
+
+## Quick start
+
+The repo ships an opinionated example config: vertical tabs collapsed to
+icons, decluttered new tab page, stripped-down toolbar, vim-style hjkl
+shortcuts. [`examples/all.toml`](examples/all.toml) bundles all three
+namespaces; [`shortcuts.toml`](examples/shortcuts.toml),
+[`settings.toml`](examples/settings.toml), and
+[`pwa.toml`](examples/pwa.toml) are single-namespace variants.
+
+![Brave with the minimal config — empty new tab page, vertical tabs collapsed to icons, decluttered toolbar](docs/img/minimal-brave.png)
+
+**Scaffold a starter config from scratch:**
+
+```bash
+dotbrave init                # write commented template to stdout
+dotbrave init -o brave.toml  # ...or to a file
+```
+
+**Or apply the example directly from GitHub** — no clone, no install.
+Fetched payloads are echoed with byte size + SHA-256 so you can see exactly
+what's being applied:
+
+```bash
+uvx dotbrave apply --dry-run \
+  https://raw.githubusercontent.com/xom11/dotbrave/main/examples/all.toml
+
+# Apply. If Brave is already running, dotbrave uses live apply;
+# first-time live setup closes Brave normally and relaunches it once.
+uvx dotbrave apply \
+  https://raw.githubusercontent.com/xom11/dotbrave/main/examples/all.toml
+```
+
+Prefer to inspect / customise locally first? Download then apply:
+
+```bash
+curl -fsSL -o brave.toml https://raw.githubusercontent.com/xom11/dotbrave/main/examples/all.toml
+# edit brave.toml ...
+uvx dotbrave apply brave.toml
+```
+
+Anything you later remove from your config reverts to Brave's default on
+the next `apply` — no orphan entries.
+
+## Install
+
+```bash
+pipx install dotbrave     # global, isolated venv
+uvx dotbrave <args>       # run on demand, no install step
+pip install dotbrave      # into the active environment
+```
+
+Run from a branch: `uvx --from git+https://github.com/xom11/dotbrave dotbrave <args>`.
+Local dev: `pip install -e ".[test]"`. Nix users: the repo ships a flake
+(`nix run github:xom11/dotbrave`).
+
+## Build your own config
+
+A single TOML carries `[shortcuts]`, `[settings]` and `[pwa]`. One `apply`
+writes all three in a single backup + write cycle.
+
+```toml
+# brave.toml
+[shortcuts]
+toggle_sidebar = ["Control+Shift+KeyE"]
+toggle_ai_chat = ["Alt+KeyA"]
+
+# vim-style hjkl
+back                = ["Alt+KeyH"]
+forward             = ["Alt+KeyL"]
+select_previous_tab = ["Alt+KeyJ"]
+select_next_tab     = ["Alt+KeyK"]
+
+# Same chord on all OSes — Meta+ = Cmd on macOS, Super on Linux/Windows (auto-translated)
+new_tab   = ["Control+KeyT", "Meta+KeyT"]
+close_tab = ["Control+KeyW", "Meta+KeyW"]
+
+[settings]
+"brave.tabs.vertical_tabs_enabled"   = true
+"brave.tabs.vertical_tabs_collapsed" = true
+"bookmark_bar.show_on_all_tabs"      = false
+
+[pwa]
+# Force-installed Progressive Web Apps. Brave fetches each manifest,
+# downloads icons, registers the app in chrome://apps, and emits a
+# launcher (.desktop on Linux, app shim on macOS, Start Menu shortcut on
+# Windows). Removing a URL + re-applying = uninstall.
+urls = [
+  "https://squoosh.app/",
+  "https://app.element.io/",
+]
+```
+
+```bash
+dotbrave apply brave.toml --dry-run    # preview the diff
+dotbrave apply brave.toml              # live apply if Brave is running
+```
+
+- **Shortcut keys**: Chromium [KeyEvent codes](https://www.w3.org/TR/uievents-code/)
+  joined by `+` — `Control+Shift+KeyP`, `Alt+Digit1`, `F11`. `Meta+` is
+  auto-translated to `Command+` on macOS, so one config works everywhere.
+- **Setting keys**: dotted paths into the profile `Preferences` JSON.
+  MAC-protected keys (`homepage`, default search engine, `pinned_tabs`, …)
+  are refused with a clear error — Brave would silently reset them on
+  launch. Run `dotbrave settings blocked` to see what's protected.
+- **PWA URLs**: every entry installs with
+  `default_launch_container = "window"` and `create_desktop_shortcut = true`.
+  `[pwa]` is the only namespace that needs elevated privileges: it writes a
+  managed-policy file (sudo on Linux/macOS) or the Windows Registry
+  (Administrator). No `[pwa]` diff → no elevation prompt.
+- **Empty header** (e.g. `[settings]` with no entries) wipes everything
+  dotbrave previously managed in that namespace. **Missing header** = skip
+  the namespace entirely.
+
+## CLI reference
+
+Shape: `dotbrave [profile-flags] <action> [action-flags] [args]`.
+Profile flags may be given **before or after** the action name — the
+after-action form wins when both are present. `export` is the inverse of
+`apply`: produce a round-trippable TOML from the current profile state.
+
+### Profile flags
+
+| Flag | Default | What it does |
+|---|---|---|
+| `-r, --profile-root PATH` | auto-detected | Brave's root profile directory. |
+| `-p, --profile NAME` | `Default` | Profile directory name inside the root — e.g. `"Profile 1"`. |
+| `--channel {stable,beta,nightly}` | `stable` | Release channel; auto-detects the `Brave-Browser-Beta` / `-Nightly` profile path and targets the matching process. |
+
+| Channel | Linux | macOS | Windows |
+|---|---|---|---|
+| stable | `~/.config/BraveSoftware/Brave-Browser` | `~/Library/Application Support/BraveSoftware/Brave-Browser` | `%LOCALAPPDATA%\BraveSoftware\Brave-Browser\User Data` |
+| beta / nightly | same, with `-Beta` / `-Nightly` suffix | same, with suffix | same, with suffix |
+
+Snap and Flatpak installs (stable only) are probed automatically on Linux.
+
+```bash
+dotbrave apply -r /custom/path -p "Profile 1" brave.toml
+dotbrave apply --channel beta brave.toml
+```
+
+### Actions
+
+| Action | What it does |
+|---|---|
+| `init [-o FILE]` | Scaffold a commented starter TOML. Refuses to overwrite. |
+| `apply [-n] CONFIG` | Apply `[shortcuts]` + `[settings]` + `[pwa]` from a file or HTTPS URL. `-n/--dry-run` previews the diff. URL fetches print size + SHA-256; pin with `--expect-sha256 HEX`; plain HTTP refused unless `--allow-http`. |
+| `export [-o FILE] [-a]` | Emit `[shortcuts]` (only bindings that differ from Brave defaults; `-a/--all-shortcuts` lifts the filter) plus `[pwa]` as round-trippable TOML. `[settings]` is intentionally omitted — Chromium exposes no defaults table, so diff-vs-default is not computable. |
+| `restore [--list] [--from FILE] [-n]` | Restore Preferences from a backup created by `apply` (most recent by default) and clear dotbrave sidecars. Does not touch `[pwa]` policy. |
+| `shortcuts dump [-a] [-o FILE]` | Emit current bindings as TOML (default: only user-customised ones). |
+| `shortcuts list [FILTER]` | List every bindable command name (substring filter). |
+| `settings dump [KEYS...] [-o FILE]` | Dump managed keys, or explicit dotted paths. |
+| `settings blocked [-o FILE]` | List MAC-protected keys `apply` will refuse, with current values. |
+| `pwa dump [-o FILE]` | Emit currently force-installed PWA URLs as a `[pwa]` table. |
+
+Every action has detailed `--help` with safety notes and examples.
+
+## How it works
+
+When Brave is closed, `dotbrave` patches the profile `Preferences` JSON
+directly. Each offline apply takes one timestamped backup, writes
+atomically (temp file + rename), and verifies the result by reloading.
+
+When Brave is running, plain `apply` uses Brave's privileged UI APIs over
+a private loopback DevTools endpoint: ordinary settings go through
+`chrome.settingsPrivate`, New Tab settings through live New Tab UI
+actions, and shortcuts through the Settings `CommandsService`. Supported
+changes take effect without restarting. A Brave not yet carrying the
+endpoint closes normally and relaunches once; a setting without a live
+route falls back to the same normal-close + verified offline write. A
+config whose only diff is `[pwa]` skips the endpoint entirely — the
+managed policy is written while Brave keeps running, and Brave loads it
+at its next launch. The endpoint binds to `127.0.0.1` only, and there is
+no force-kill switch.
+
+`[shortcuts]` and `[settings]` track managed entries in sidecar files
+(`Preferences.dotbrave.{shortcuts,settings}.json`), so removing a key from
+your config restores Brave's default on the next apply. `[pwa]` state
+lives in Chromium's managed-policy storage (Linux JSON file, macOS plist,
+Windows Registry) — the policy *is* the state.
+
+On macOS, `/Library/Managed Preferences/` is a system-managed cache that
+gets reclaimed at boot on non-MDM machines, which would otherwise
+uninstall your PWAs. To keep them installed, `apply` installs a small
+root-owned self-healing helper:
+
+- `/Library/LaunchDaemons/org.dotbrave.com.brave.Browser.pwa.plist` —
+  watches the managed-preferences directory and rewrites the policy if
+  macOS removes it.
+- `/Library/Application Support/dotbrave/com.brave.Browser.managed.plist`
+  and `com.brave.Browser.heal.sh` — the policy source of truth and the
+  rewrite script.
+
+Applying an empty `[pwa]` table (`urls = []`) removes all of the above.
+
+### Brave install methods
+
+| Install | Auto-detected | `[pwa]` works | Notes |
+|---|---|---|---|
+| `.deb` / `.rpm` / Arch / NixOS | yes | yes | Reference install; full support. |
+| **Snap** | yes | **refused with clear error** — sandbox doesn't read `/etc/brave/policies/managed/` | Use `.deb` for `[pwa]`. |
+| **Flatpak** | yes | **refused with clear error** — same sandbox limitation | Relaunch goes back through `flatpak run`. |
+| **macOS** `.dmg` | yes | yes | Includes cfprefsd cache invalidation + self-healing daemon. |
+| **Windows** installer | yes | yes — writes `HKLM\Software\Policies\BraveSoftware\Brave`; requires Administrator | |
+
+## Coming from dotbrowser?
+
+`dotbrave` is a standalone extraction of dotbrowser's Brave support with
+its own state names: sidecars are `Preferences.dotbrave.*.json` (was
+`Preferences.dotbrowser.*.json`) and the macOS daemon is
+`org.dotbrave.<bundle>.pwa` (was `org.dotbrowser.<bundle>.pwa`). Your
+Brave profile itself is untouched by the switch, but entries previously
+managed by dotbrowser are not tracked by dotbrave until you `apply` your
+config once with dotbrave. On macOS, remove dotbrowser's daemon
+(`dotbrowser brave apply` with an empty `[pwa]` table, or the manual
+`launchctl bootout` steps in its README) before letting dotbrave manage
+`[pwa]`, so two daemons don't fight over the same plist.
+
+## Caveats
+
+- **Brave Sync** can overwrite `[settings]` entries on its next pulse if
+  they fall in a synced category. UI-layout keys like
+  `brave.tabs.vertical_tabs_*` are local-only and immune. `apply` prints a
+  non-fatal warning when `sync.has_setup_completed=true`.
+- A handful of settings (`homepage`, default search engine, `pinned_tabs`,
+  …) are integrity-protected and refused rather than silently reset by
+  Brave on next launch. Set those in the Brave UI.
+- **`[pwa]` is force-install** (Chromium's enterprise
+  `WebAppInstallForceList`). Apps appear in `chrome://apps` with an
+  "Installed by your administrator" label and hidden right-click Remove —
+  uninstall by deleting the URL from `[pwa]` and re-applying. That is the
+  right semantics for dotfile-style management (the TOML is the source of
+  truth), but worth knowing if you also install PWAs by hand.
+
+## License
+
+MIT