diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 0f9c7452b41..b6ffb63b826 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -16,7 +16,7 @@ pnpm dev `pnpm dev` in a linked Git worktree uses its own profile and ports, so instances in different worktrees run side by side. -See [`docs/development.md`](../docs/development.md) for per-OS packages, Corepack and Windows notes, dev profiles and seeding, the pnpm global virtual store, cross-architecture and Linux (Docker) builds, and dev server options. +See [`docs/development.md`](../docs/development.md) for per-OS packages, Corepack and Windows notes, dev profiles and seeding, cross-architecture and Linux (Docker) builds, and troubleshooting. ## Branch Naming @@ -60,13 +60,13 @@ pnpm test:changed src/main/runtime --maxWorkers=2 # staged, unstaged, and untr pnpm test --changed=origin/main --maxWorkers=2 # also commits since the merge base ``` -Affected tests follow Vitest's static import graph, so run suites explicitly for dynamic imports, fixtures, or subprocess inputs. Local affected tests do not replace CI. If a file passes alone but fails after others, add `// @orca-isolated-worker` to it. More detail is in [`docs/development.md`](../docs/development.md#tests-and-dev-server-options). +Affected tests follow Vitest's static import graph, so run suites explicitly for dynamic imports, fixtures, or subprocess inputs. Local affected tests do not replace CI. If a file passes alone but fails after others, add `// @orca-isolated-worker` to it. ## Pull Requests Fill in every section of [`.github/pull_request_template.md`](./pull_request_template.md): an ELI5, what changed and why, a linked issue (required for outside contributors), a before and after (screenshots or videos) for any UI or behavior change (only if there is truly no visual or interaction change, write exactly `N/A` and briefly say why), how you tested it, the risk, and under Review a short summary from your AI coding agent covering cross-platform, SSH/remote, agent and integration compatibility, performance, UI quality, and security. Keep each PR small and focused on one topic. -Version bumps, tags, and releases are maintainer-managed. Do not include release version changes unless a maintainer asks. Maintainers: see [`docs/releasing.md`](../docs/releasing.md). +Version bumps, tags, and releases are maintainer-managed. Do not include release version changes unless a maintainer asks. Maintainers cut releases with the [Cut Release](https://github.com/stablyai/orca/actions/workflows/release-cut.yml) workflow. ## Getting Help diff --git a/.gitignore b/.gitignore index ec39c53b8df..e9ca3822d36 100644 --- a/.gitignore +++ b/.gitignore @@ -100,7 +100,6 @@ docs/** !docs/bug-reproductions/** !docs/STYLEGUIDE.md !docs/development.md -!docs/releasing.md !docs/styleguide/ !docs/styleguide/** !docs/agents-md-refs/ diff --git a/README.md b/README.md index 8daff8adc7b..79d002770f7 100644 --- a/README.md +++ b/README.md @@ -272,6 +272,8 @@ _Or via a package manager:_ brew install --cask stablyai/orca/orca # Upgrade an existing install brew upgrade --cask stablyai/orca/orca +# Release candidates (conflicts with the stable cask; uninstall it first) +brew install --cask stablyai/orca/orca@rc # Arch Linux (AUR) — or stably-orca-git to build from source yay -S stably-orca-bin diff --git a/docs/development.md b/docs/development.md index 7ed2a9f78aa..a1607c9f11a 100644 --- a/docs/development.md +++ b/docs/development.md @@ -1,67 +1,28 @@ # Orca Development Environment -Reference details for working on Orca locally. Start with [`CONTRIBUTING.md`](../.github/CONTRIBUTING.md). +Setup details beyond [`CONTRIBUTING.md`](../.github/CONTRIBUTING.md). -## Toolchain and Native Prerequisites +## Prerequisites -Install Node 24, pnpm, and the Bun version in [`config/.bun-version`](../config/.bun-version). -`pnpm test` runs Vitest on Bun, with Node workers for runtime contracts such as SQLite, -native PTYs, socket liveness, and V8 memory behavior. `pnpm test:node` runs the same suites -entirely on Node. Builds and dependency installation still use Node and pnpm. +Install Node 24, the pnpm version in `packageManager` in [`package.json`](../package.json), and the Bun version in [`config/.bun-version`](../config/.bun-version). -The server, its workers and its packaged dependencies target Node 24. The compatibility -launcher and CLI still target Node 18; the launcher hands off to bundled Node 24 before -loading server code. WSL guest programs and host discovery retain their Node 18 minimum. -Keep Node 24 APIs and server imports out of these host compatibility paths. Running an -unpackaged server directly requires Node 24 or newer. +`corepack enable` needs Corepack 0.34.5 or newer (`npm install -g corepack@latest`). On Windows it fails with `EPERM` outside an elevated shell when Node is in `C:\Program Files\nodejs`; run `npm install -g pnpm@` instead. -Use the pnpm version in `packageManager` in [`package.json`](../package.json): `corepack enable` -needs Corepack 0.34.5 or newer to start the pinned pnpm (`npm install -g corepack@latest`). On -Windows it writes shims next to `node.exe` and fails with `EPERM` outside an elevated shell when -Node is in `C:\Program Files\nodejs`; run `npm install -g pnpm@` instead. - -`pnpm install` compiles native modules such as `node-pty` with `node-gyp` and loads them in -Electron, so a fresh machine also needs: +`pnpm install` compiles native modules such as `node-pty`, so a fresh machine also needs: - **macOS**: Xcode Command Line Tools (`xcode-select --install`). -- **Windows**: Python 3 and Visual Studio Build Tools with the "Desktop development with C++" - workload. -- **Linux**: a C++ toolchain, Python 3, and the libraries Electron loads even on a headless - machine, plus `xvfb`, which the `*.electron.test.ts` files in `pnpm test` use when `DISPLAY` is - unset. On Ubuntu 24.04+ and Debian 13+: +- **Windows**: Python 3 and Visual Studio Build Tools with the "Desktop development with C++" workload. +- **Linux**: a C++ toolchain, Python 3, Electron's libraries, and `xvfb` (used by `*.electron.test.ts` when `DISPLAY` is unset). On Ubuntu 24.04+ and Debian 13+ (older releases name the last package `libasound2`): ```bash sudo apt-get update && sudo apt-get install -y build-essential python3 xvfb libgtk-3-0 libnss3 libgbm1 libasound2t64 ``` - Older releases name the last package `libasound2`. - -```bash -pnpm install -pnpm dev -``` - -`mobile/` is a separate pnpm project with its own lockfile, so the root `pnpm install` leaves its -dependencies uninstalled. `pnpm build` (`build:mobile-web` fails without them) and the lint -passes that cover `mobile/` need them. Install them before building or linting, and again -when `mobile/pnpm-lock.yaml` changes: - -```bash -pnpm -C mobile install --frozen-lockfile -``` +Re-run `pnpm -C mobile install --frozen-lockfile` whenever `mobile/pnpm-lock.yaml` changes. ## Dev Profiles and Parallel Instances -`pnpm dev` in a linked Git worktree uses its own userData profile, renderer port, and remote -debugging (CDP) port, so dev instances in different worktrees run side by side. The main checkout -keeps the shared `orca-dev` profile. Ports are derived from the worktree path and move to the next -free port when taken: renderer ports start at 15200 and CDP ports at 9333. - -On startup the runner prints one stdout line and writes the same JSON to `out/dev-instance.json`: - -```text -ORCA_DEV_INSTANCE {"userData":".../orca-dev-wt/1d3830d4d3","profile":"worktree","rendererPort":15339,"rendererUrl":"http://localhost:15339","cdpPort":9513,"cdpUrl":"http://127.0.0.1:9513","repoRoot":"...","runnerPid":4242} -``` +`pnpm dev` in a linked Git worktree uses its own profile, renderer port (from 15200), and CDP port (from 9333), so worktrees run side by side. The main checkout uses the shared `orca-dev` profile. The chosen profile and ports are printed on an `ORCA_DEV_INSTANCE` line and written to `out/dev-instance.json`. | Option | Effect | | ----------------------------------------------------------------------- | ---------------------------------------------------------- | @@ -71,109 +32,22 @@ ORCA_DEV_INSTANCE {"userData":".../orca-dev-wt/1d3830d4d3","profile":"worktree", | `REMOTE_DEBUGGING_PORT=`, `ORCA_DEV_RENDERER_PORT=` | Pin a port | | `pnpm dev --seed-profile[=]` or `ORCA_DEV_SEED_PROFILE=` | Seed an empty profile on first launch | -Per-worktree profiles live in `orca-dev-wt/` next to `orca-dev` (`~/Library/Application -Support` on macOS, `%APPDATA%` on Windows, `$XDG_CONFIG_HOME` or `~/.config` on Linux). The -automatic storage cleanup removes them once their worktree is gone and nothing still runs from -them. `config/scripts/development/launch/orca-dev.mjs` and the `orca-dev` terminal wrapper target the profile this -checkout's `pnpm dev` used. - -Seeding copies a slim set of state from another profile: projects, workspaces, settings, SSH -targets, and the Orca account session. Terminal sessions, PTY leases, automations, caches, logs, -and lock files are not copied, and the source profile is only read. The default source is -`orca-dev`, or the installed app's profile when `orca-dev` is empty. Seed from `orca-dev` when you -need the signed-in account session: dev builds cannot decrypt secrets the installed app encrypted. +Seeding copies projects, workspaces, settings, SSH targets, and the Orca account session from another profile (default `orca-dev`, else the installed app's). Seed from `orca-dev` if you need to stay signed in: dev builds cannot decrypt secrets the installed app encrypted. ```bash pnpm dev:seed-profile [--from=] [--to=] [--reset] pnpm dev:fresh [--keep] [--seed-from[=]] # temporary profile, removed on exit ``` -## Tests and Dev Server Options +## Installs and Builds -Use a test file or directory when you know the relevant suites. For dependency-based -feedback, Vitest can select tests affected by your edits: +- Local installs use pnpm's global virtual store (`~/pnpm/store`) shared by all worktrees. Do not keep a `node_modules` in your home directory: it hides missing-dependency bugs. Set `ORCA_PNPM_GLOBAL_VIRTUAL_STORE=0` in your shell to opt out. +- Before a cross-architecture build (including `pnpm build:mac`, which builds x64 and arm64), run `pnpm install:release`. +- On Linux, `pnpm build`, `pnpm build:native`, and packaging need a running Docker daemon for the clipboard helper. For native Wayland development, run `pnpm build:native` before `pnpm dev`. See the [clipboard build guide](../native/wayland-clipboard/README.md#building-and-testing). -```bash -pnpm test:changed src/main/runtime --maxWorkers=2 -pnpm test --changed=origin/main --maxWorkers=2 -pnpm test src/shared/automations/scheduling/automation-cron-input-validation.test.ts --maxWorkers=2 -``` +## Troubleshooting -`test:changed` considers staged, unstaged, and untracked files. `--changed=origin/main` -also includes committed changes since the branch's merge base. Update that ref when -you need a newer baseline. Both accept the same path filters and options as `pnpm test`. -When Git reports no changed files at all, the launcher exits before starting Vitest. - -Affected tests use Vitest's static import graph. Run suites explicitly for computed -dynamic imports, fixture files, subprocess inputs, or other dependencies outside that -graph. Local affected tests do not replace CI. - -Use `pnpm test`, not raw `vitest`: only it keeps the transform cache that makes repeat runs fast. - -Most unit files share a worker and its module cache with the files before them. After each file -the worker undoes mocks, fake timers, stubs, env, cwd, and leftover timers, listeners, and globals. -Files using `vi.doMock`, `vi.resetModules`, a DOM environment, or direct `globalThis` writes keep -their own worker. If a file passes alone but fails after others, add `// @orca-isolated-worker` -to it; `ORCA_VITEST_ISOLATE_EVERY_FILE=1` isolates every file to confirm a leak. - -To reduce main-process rebuild CPU and memory when you do not need its source maps, -set `ORCA_DEV_MAIN_SOURCEMAPS=0` before `pnpm dev`. In Bash/zsh: - -```bash -ORCA_DEV_MAIN_SOURCEMAPS=0 pnpm dev -``` - -In PowerShell, use `$env:ORCA_DEV_MAIN_SOURCEMAPS='0'` before `pnpm dev`. -Remove the variable when debugging the main process with source maps. Renderer and -preload settings are unaffected; production builds always keep their hidden main maps. - -`pnpm dev` serves the renderer with Vite's bundled dev mode: a few bundled chunks instead of -thousands of module requests, so the first render and full reloads are faster. While a rebuild is -pending, a newly opened pop-out, space, or web window may briefly get placeholder HTML. If the -renderer misbehaves, set `ORCA_DEV_BUNDLED=0` (PowerShell: `$env:ORCA_DEV_BUNDLED='0'`) and report it. - -Local installs use pnpm's global virtual store: each package version is one slot -under `~/pnpm/store` that every worktree links to, instead of a full `node_modules` per worktree. -An existing worktree converts on its next `pnpm install`, and an older branch without the setting -converts back the same way. CI always uses the normal layout. On Windows, pnpm links with -junctions when you lack the symlink privilege, so no administrator rights or Developer Mode are -needed. Things to know: - -- Keep `~/node_modules` (and any other `node_modules` above the store) out of your home - directory. Node resolves upward from the store slot, so a stray one there supplies - dependencies the package never declared and hides missing-dependency bugs; `pnpm install` warns - when it finds one. -- Native addons are never rebuilt in place in a shared slot: each CPU gets its own build - beside it (see [`native-build-entry.cjs`](../config/scripts/native-build/node-addons/native-build-entry.cjs)), so - cross-arch packaging is safe for other worktrees. -- `ORCA_PNPM_GLOBAL_VIRTUAL_STORE=0` opts out. Keep it set - in your shell: `pnpm run` re-checks the install and relinks a worktree whose layout no longer - matches. - -Ordinary installs include native optional dependencies for the current OS and CPU only. -Before a cross-architecture build (including `pnpm build:mac`, which produces both x64 and -arm64 artifacts by default), run `pnpm install:release` to add the other CPU's variants. - -Linux `pnpm build`, `pnpm build:native`, and Linux packaging require a running Docker -daemon to build the clipboard helper against Ubuntu 20.04 rather than the host's -newer libraries. A verified cached helper can be reused without Docker. For native -Wayland development, run `pnpm build:native` before `pnpm dev` to make text copying -available. See the [clipboard build guide](../native/wayland-clipboard/README.md#building-and-testing). -macOS and Windows builds do not use this helper or require Docker for it. - -## Lint and Typecheck - -`pnpm lint` runs independent checks in a bounded pool. Use -`pnpm lint --maxWorkers=2 --timings` to limit concurrent checks and print their durations. - -For repeated local typechecks, use `pnpm tc` (or `pnpm tc:node`, `pnpm tc:web`, -and `pnpm tc:cli`). On Apple Silicon macOS and x64/arm64 Linux, these use the pinned -`tsrs` compiler with incremental caches. Keep `.cache/typecheck/` between checks; -delete it to force a fresh check. Caches are separate for each project, compiler -version, and worktree. At most two projects run together, subject to the memory budget. -Windows, Intel macOS, and other unsupported platforms use pinned Bun automatically. -Pass `--compiler=bun` to explicitly use Bun, or `--compiler=native` to use TypeScript. -CI uses `pnpm typecheck:ci`, which explicitly selects Bun and its CI concurrency. -Shared tests are checked by the -Node project; shared production code is checked in all three environments. -Run `pnpm tc:node` after editing shared tests, or `pnpm tc` to check everything. +- Slow main-process rebuilds: set `ORCA_DEV_MAIN_SOURCEMAPS=0` before `pnpm dev` when you don't need main-process source maps. +- Renderer misbehaving in dev: set `ORCA_DEV_BUNDLED=0` to turn off bundled dev mode, and report it. +- Test passes alone but fails after others: add `// @orca-isolated-worker` to the file; `ORCA_VITEST_ISOLATE_EVERY_FILE=1` isolates every file to confirm a leak. +- Slow typechecks: where supported, `pnpm tc` keeps incremental caches in `.cache/typecheck/`; delete it to force a fresh check. diff --git a/docs/releasing.md b/docs/releasing.md deleted file mode 100644 index 02ca4717c5a..00000000000 --- a/docs/releasing.md +++ /dev/null @@ -1,63 +0,0 @@ -# Releasing Orca - -## Release Process - -Version bumps, tags, and releases are maintainer-managed. Do not include release version changes in a normal contribution unless a maintainer asks for them. - -### Cutting a release (maintainers) - -All releases are cut from the **Cut Release** GitHub Actions workflow. There is no local `pnpm release:*` script — running releases locally is too easy to get wrong (dirty tree, wrong branch, stale main). - -**To cut a release:** - -1. Open [Actions → Cut Release](https://github.com/stablyai/orca/actions/workflows/release-cut.yml). -2. Click **Run workflow** and pick: - - **kind**: one of `rc`, `patch`, `minor`, `major`. - - **ref**: the branch, tag, or SHA to build from. Defaults to `main`. -3. Run it. - -The workflow resolves the next version from GitHub Releases, bumps `package.json`, tags, pushes, and runs the multi-platform build + publish inline. - -**How the next version is chosen:** - -All stable kinds (`patch`, `minor`, `major`) are computed off the latest _stable_ release, ignoring any RCs in between. - -- `kind=rc` + last tag was stable (e.g. `v1.3.14`) → `v1.3.15-rc.0`. -- `kind=rc` + active RC series (e.g. `v1.3.15-rc.2`) → `v1.3.15-rc.3`. -- `kind=patch` + latest stable `v1.3.14` → `v1.3.15` (regardless of any intermediate RCs). -- `kind=minor` + latest stable `v1.3.14` → `v1.4.0`. -- `kind=major` + latest stable `v1.3.14` → `v2.0.0`. - -**Safety guarantees:** - -- Stable releases are refused if the new version isn't strictly greater than the latest published stable. This is the only rule `electron-updater` actually needs — it compares semver within the `latest` channel, so a regressing stable is the one thing that breaks auto-update for fresh installs. -- Complete RC draft releases created by the release workflow are published before cutting a new tag only when the draft tag was built from the current release ref. Stale drafts are skipped so fixes cut a fresh RC instead of exposing old artifacts. -- If the latest RC tag exists but is still draft-only or missing its GitHub Release, the workflow resumes that tag only when it was built from the current release ref. Otherwise the next RC number is cut. -- RC numbering also considers release commits on `main`, so deleting a stale tag does not let a later cut reuse the same RC number. -- Off-main releases (when `ref` is not the tip of `main`) only push the tag. `main` is never mutated from a non-main ref, so you can safely release an older commit without polluting history. -- When `ref` is the tip of `main`, the workflow tries to fast-forward the version-bump commit onto `main`. If main requires pull requests, it leaves main unchanged and pushes only the release tag. Other push errors still stop the cut. - -**Common scenarios:** - -- **Normal release:** `kind=patch`, `ref=main`. -- **"A bad commit just landed on main, release the commit before it":** `kind=patch`, `ref=`. `main` is left alone; the tag points at the good SHA. Fix forward on `main` afterward. -- **One-off RC for a feature branch:** `kind=rc`, `ref=`. Produces an RC tag that does not touch `main`. -- **Minor or major bump:** `kind=minor` or `kind=major`. - -## Release Channels - -The public Homebrew cask tracks stable desktop releases: - -```bash -brew install --cask stablyai/orca/orca -``` - -Release candidates use a separate cask token: - -```bash -brew install --cask stablyai/orca/orca@rc -``` - -The two casks conflict because both install `Orca.app`. Switch channels with a -normal `brew uninstall --cask` followed by the install for the other channel. -Do not use `--zap` unless you intentionally want to remove local Orca state.