bcore handles Brave Core checkout operations: readiness checks, sync, build, test, run, and related inspection. It is not the general entry point for Brave developer tooling. A feature belongs here because it operates on a Core checkout, not merely because Core developers use it.
scripts/
bcore, bpm, sync-support-repos launchers (POSIX sh); resolve their own installation
pyproject.toml project metadata; no dependencies
.venv/ scaffold runtime (ignored)
schemas/ versioned JSON schemas for results
src/scaffold/
launch.py interpreter check, then dispatch
entry.py launcher name to command line
common/ shared, product-neutral pieces
brave/ Brave commands
tests/{unit,integration,acceptance}/
Tooling code, launchers, and tests live under scripts/; there is no root src/ or tests/.
| Module | Responsibility |
|---|---|
support.py |
Separate support-repository CLI, manifest validation, Git sync and prune |
common/results.py |
Result envelope, exit codes, error type, text rendering |
common/config.py |
TOML parsing, validation, in-place record edits |
common/identity.py |
Checkout discovery, selection, Git linked-worktree detection |
common/env.py |
Pure export derivation, direnv approval, explicit loading, identity checks |
common/tools.py |
Checkout-local Node/package-manager/Python inspection and argv construction |
common/procs.py |
Subprocess execution, command logs, redaction, cancellation |
common/notify.py |
Notification policy, operation classification, message text, the macOS and terminal-bell delivery backends (BCORE_NOTIFY_BACKEND=none disables both; tests set it) |
common/cli.py |
Option parsing, forwarding rules, help rendering |
common/checks.py |
Check records and readiness aggregation |
common/platforms.py |
Targets and the capability table |
brave/registry.py |
The command table: parsing, help, and dispatch all read it |
brave/execution.py |
The selected checkout's execution context: identity, approved environment, resolved tools |
brave/patch_inventory.py, brave/sync_scope.py |
Patch inventory, dependency repository discovery, and tracked-change snapshots |
brave/cmd_build.py, brave/cmd_patches.py, brave/cmd_tools.py, brave/cmd_setup.py, brave/clean.py, brave/android.py, brave/doctor.py |
Command handlers and their platform code |
brave/sync.py |
Sync arguments, the target list kept across syncs, and dispatch to Core's sync command |
brave/packages.py |
The one place a package command is turned into a child process (bpm and every phase use it) |
brave/branch_tests.py, brave/cmd_test.py |
Changed-test and named-file discovery, mapping to suites and filters (read-only Git), and the multi-suite runner behind bcore test |
brave/android_tests.py |
Android test suites, the required support branch, the Core test overlay, device arguments, and result checks |
brave/patches.py, brave/android_deps.py, brave/freshness.py |
Patch preparation, Android support preparation, and freshness evidence |
brave/support_scripts.py, brave/support_script_contracts.json |
Reviewed shell identities and complete support write manifests |
brave/records.py, brave/steps.py |
Operation records with phase outcomes, per-output history, and the step descriptions shared by plans and records |
Handlers receive a context and return a Result or raise ScaffoldError; the runner turns either into exactly one output document.
python3.14 -m venv --without-pip scripts/.venv
cd scripts
.venv/bin/python -m unittest discover -s tests -t . # serial, about twelve minutes
.venv/bin/python -m tests.run_parallel # the same tests, modules in parallelTests use only the standard library. Fast suites need no real checkout, SDK, credentials, or shell configuration: they build disposable checkouts with fake Node, package-manager, and vpython3 executables, use a temporary HOME and direnv data directory, and run the real launchers and a real direnv. Fixtures live in scripts/tests/support.py. In a sandbox only, tests approve environments with direnv allow; nothing approves a real environment.
- A macOS host. Restart, launch, and application tests use fake
.appbundles,ps,open, andosascript; the integration classes skip elsewhere. direnvonPATH. Tests run a realdirenvwith a private data directory; without it they skip.- A C compiler (
cc, from the Xcode command line tools). Fake applications run a small executable the suite compiles once, because copies of system binaries are killed on macOS. Without a compiler the fake applications cannot stay running and the restart tests fail. - Process inspection.
psmust be allowed; a sandbox that denies it fails the restart tests. - Git, and
git-lfsfor the large-file tests (they skip without it). No network access is needed. - Python 3.14+ as the scaffold runtime.
The full suite takes about twelve minutes serially. tests.run_parallel runs each test module as its own process, up to --jobs N at a time (default: the core count, at most 8), and finished in about 2½ minutes on an 8-job run; the longest single module, test_android, sets the floor. It takes module names or files (tests.run_parallel --jobs 4 tests/unit/test_buildopts.py) and --suite unit|integration, prints each module as it finishes and the output of any that fail, and exits non-zero if any module fails or runs no tests. It leaves out tests/acceptance, which needs a real checkout. Test sandboxes are disposable and separate, so modules do not interfere, and the sandbox environment sets BCORE_NOTIFY_BACKEND=none, so no test run raises a desktop notification. Run a focused set while you work, for example .venv/bin/python -m unittest tests.integration.test_clean tests.integration.test_plans, or one unit module such as tests.unit.test_buildopts; unit tests need no direnv, and integration classes name what they need in their skip messages. The one timing-sensitive test is RestartLoggingTests.test_liveness_and_launch_probes_are_logged_with_polling_summarised: on a heavily loaded machine it can see fewer liveness polls than it expects; rerun it alone before treating it as a fault. Each test sandbox stops every process that mentions its directory when it finishes, so a run leaves nothing behind. test_doc_examples runs the command examples from the guides in fixtures; a new example in a guide must be added to its table (or listed with the reason it cannot run) or a coverage test fails.
.github/workflows/tests.yml runs the whole suite through tests.run_parallel on an Apple-silicon macOS runner for pull requests, pushes to main, and manual runs. It installs Python 3.14, Node.js, and direnv, creates scripts/.venv without pip, and needs no credentials or network access beyond the installs. Actions are pinned by commit SHA with a version comment. The real-checkout acceptance checks never run there.
Real-checkout acceptance runs are opt-in, use an explicitly selected checkout, and need the user's authorization for the operations involved (agent workflows). Record the checkout, operations, and results with the evidence.
- Add a
CommandSpectobrave/registry.pywith a summary, positionals, options, side effects, and examples. Help and parsing come from it. - Write the handler. Take the checkout from
ctx.identity(), load its environment once withbrave/execution.load(resolve tools withexecution.resolve_tools), pass thatExecutionto every phase, and run processes throughcommon/procs(package commands throughbrave/packages.run) so they are logged and cancellable. Record each phase withop.start,op.succeed, andop.fail. - Return a
Result; raiseScaffoldErrorwith a stable code and repairs. - Add the command's
datashape toschemas/command-data.schema.jsonand select it inschemas/result-envelope.schema.json; a test fails for a command without one. Add tests through the real launcher, including the failure paths: the suite validates real results (success, unresolved output, error, cancellation, plans) against the schemas and checks that help examples parse. - Update
docs/commands.md, the troubleshooting entry for new errors, and the capability table. - For a doctor check, add it to a check group and the group to a scope in the tables in
brave/doctor.py; execution paths reuse the same functions. Groups other than machine, shell, and signing run in the selected checkout's approved environment.
brave/sync.py runs Core's package sync script through brave/packages.py. Core controls source updates, resets, package installation, patches, and hooks. Scaffold selects the checkout, resolves local tools, combines mobile targets, forwards arguments, streams output, and records the result. A failed sync stops later phases and leaves the checkout as Core left it.
Plans describe the command and general checkout writes. They do not evaluate Core's sync implementation or promise preservation of local work. Keep sync independent of source hashes, hook inventories, and overwrite approval.
brave/sync_scope.py provides dependency discovery and tracked-change snapshots for build freshness and Android support checks. Those checks and patch preparation guards belong to their respective operations, not the sync phase.
Regression tests exercise dispatch with local changes, changed Core scripts, forwarded options, and child failures. Use isolated fake package commands to verify that Scaffold passes control to Core without editing the checkout first.
scripts/src/scaffold/brave/android_support.toml defines the support branch in support.default_ref. Setup, Android test checks, repair commands, help, and overlay messages use that value. Change it there when the branch is renamed; update the branch examples in the Android guide, troubleshooting guide, and project skills at the same time. Existing support working copies are never switched automatically.
A combination is supported in the capability table only after it has run on a real checkout; add it to VALIDATED in common/platforms.py in the change that records that evidence. Fixture results never justify supported.
New first-party source, tests, scripts, and comment-capable configuration carry the MPL header shown in AGENTS.md. Commits use Conventional Commits and follow the signing procedure there.