Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
257 changes: 25 additions & 232 deletions README.md

Large diffs are not rendered by default.

10 changes: 7 additions & 3 deletions docs/demo.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ The [drivers](testing.md) assert; `npm run demo` performs. Same Playwright, same
class names — but paced in beats rather than in milliseconds, and it films itself:

```bash
npm run demo -- --record # the whole product, no model calls, to a .mov
npm run demo -- --record # cached world: no new model calls; first run seeds it
npm run demo -- --record --live # plus a real turn, an approval card, a question,
# a bot at work — its face looking down at the page —
# writing its own memory, and what it kept
Expand All @@ -19,8 +19,9 @@ It needs Screen Recording permission for whatever is running it; without that th
out empty and the run says so.

The capture is then re-encoded, because the raw one is not a file anybody wants to be sent.
`screencapture` records at the display's own resolution and refresh rate — retina, at **120
fps** — which is around 45 MB for three minutes of a mostly stationary window, and nothing in
`screencapture` records at the display's own resolution and refresh rate — retina at
120 fps on the display used for the original recording — which produced
around 45 MB for three minutes of a mostly stationary window, and nothing in
its flag list changes that. So it is fixed afterwards: halved to logical resolution, dropped to
30 fps, and encoded at a CRF where the app's own text is still sharp at 1:1. That is about 4 MB
for the same footage. `--width 0` keeps the retina resolution, `--crf` and `--fps` move the
Expand Down Expand Up @@ -48,6 +49,9 @@ filmed. With both redirections the session list, the recents, the bots, the colu
file tree are all the world's. `/Users/Shared` rather than the home directory because every path in
it ends up on screen, and a home directory has somebody's name in it.

The projects under `scripts/demo/project/` are fictional demo fixtures; their READMEs
describe the sample world rather than this application's setup.

The world holds two invented checkouts — `harbour-lights` and `tide-tables`, copied out of
`scripts/demo/project/` — the sessions the demo earned in them, two resident bots (`RESIDENT_BOTS`:
one never spoken to, one with a session and a line in its memory file, so the bots scene has a
Expand Down
66 changes: 66 additions & 0 deletions docs/development.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
# Development and packaging

Start with [setup](setup.md), then use these commands from the repository root.

| Command | What it does |
| --- | --- |
| `npm ci` | Install locked npm dependencies and set up Electron |
| `npm run dev` | Set up Electron, build both Rust executables, start hot reload |
| `npm run bridge` | Build `bravebot-rpc` and `bravebot-ui-files`, loading credentials where configured |
| `npm run setup:electron` | Install the Electron runtime if needed and name the development app |
| `npm run name-dev-app` | Restore “Brave Bot” as the development app's menu-bar name |
| `npm run typecheck` | Run `tsc --noEmit` |
| `npm run build` | Build both Rust executables, typecheck, bundle into `out/` |
| `npm start` | Set up Electron and preview the existing bundle; does not rebuild it |
| `npm run package` | Build both Rust executables, bundle, package a macOS `.app`; does not typecheck |
| `cargo test --all` | Test the Rust workspace |
| `cargo clippy --all-targets --all-features -- -D warnings` | Lint the Rust workspace |
| `npm run drive` / `npm run drive:<name>` | Run a named Electron driver; see [testing](testing.md) |
| `npm run demo -- --record` | Record a walkthrough; see [demo costs and setup](demo.md) |

TypeScript uses strict checking, including `noUncheckedIndexedAccess`,
`noUnusedLocals` and `noUnusedParameters`. There is no ESLint or Prettier gate.
See [testing](testing.md#what-ci-runs) for exactly what CI checks and what must run locally.

## Build and preview

```bash
npm run build
npm start
```

`scripts/build-bridge.sh` builds the Rust bridge and secure-file helper. TypeScript
then checks the code and electron-vite bundles the main process, preload and React
renderer into `out/`. Development executables are in `target/debug/`.

The bridge talks to the pinned agent library over a child-process protocol; it does
not drive a terminal. See the [protocol design](phase-0-rpc-protocol.md) and
[security boundaries](security.md).

## Packaging

```bash
npm run typecheck
npm run package
```

`npm run package` does not typecheck. It builds the Rust executables and Electron
bundles, then `scripts/package.mjs` uses `@electron/packager` to create
`dist/Brave Bot-darwin-<arch>/Brave Bot.app`. The architecture follows the Node
process (`arm64` or `x64`). Rust uses its configured toolchain target; for a native
bundle, use matching Node and Rust architectures.

Both `bravebot-rpc` and `bravebot-ui-files` are copied into the app's Resources.
Packaged builds use those copies; development builds use `target/debug/`.
The script currently packages debug Rust executables, and performs no app signing
or notarisation. The resulting bundle is for local testing, not a completed
release-distribution pipeline. Git commit signatures are separate from macOS app signing.

A development checkout can produce a configured or unconfigured binary depending
on the build environment. Follow [credentials](setup.md#credentials) before packaging
for inference; Finder does not load shell configuration. Packaging itself does not
check that backend credentials exist.

To check the bundle, use the [packaged-app drivers](testing.md#current-regression-checks).
AppKit takes the menu-bar name from the bundle's `CFBundleName`; changing
`app.name` would also change Electron's user-data location.
Loading
Loading