mirror of
https://github.com/stablyai/orca.git
synced 2026-10-21 16:03:26 +00:00
Jinwoo-H
b0a8401265
Orca's remote-server feature pairs a desktop client to a remote Orca runtime, and users update the two independently, so mixed versions are the normal state. Until now nothing ran an old client against a new server or the reverse. Every cross-version claim rested on code reading plus unit tests built from hand-written old and new shapes, which cannot catch a real skew regression. This adds a two-point compatibility matrix that loads the REAL host RPC methods, the real RpcDispatcher, and the real renderer terminal multiplexer from two builds — the working tree and the newest release tag — and drives them against each other over an in-process transport that reproduces production frame routing, including the host-side decode that drops unknown opcodes without an error. One scripted journey runs per pairing: subscribe, input reaching the process, live output, hide/reveal buffer snapshot, transport drop, resubscribe, and input landing again. The oracle asserts the journey actually executed rather than that nothing threw: the recorded step list, the exact named frame sequence, both subscribed events with their negotiated capabilities, the exact input texts the host wrote to the PTY, the rendered snapshot and output content, and an empty set of frames refused by either decoder. A host runtime method the harness does not stub is reported by name, so a harness gap can never be misread as a wire break. Detection is proven per rule by injecting each violation and reverting it. Adding an optional snapshot field kept every pairing green; making the client require that field turned only new-client/old-server red. Adding opcode 17 and sending it ungated turned new-client/old-server red with the rejected opcode named, while old-client/new-server stayed green. Making the host stop publishing the snapshot `source` field turned both new-server pairings red and left the old-server pairing green. docs/reference/remote-wire-compatibility.md writes the three rules down, and a dedicated CI job runs the harness with fetch-depth 0 because the sharded test lane's shallow clone has no tags; that lane now excludes the harness explicitly. Refs STA-3469.
66 lines
5.5 KiB
Markdown
66 lines
5.5 KiB
Markdown
# Design System
|
|
|
|
All UI work — layout, color, typography, spacing, component selection, UX behavior — must follow [`docs/STYLEGUIDE.md`](./docs/STYLEGUIDE.md). Use the tokens defined in `src/renderer/src/assets/main.css` (the canonical source) and the shadcn primitives in `src/renderer/src/components/ui/`. Don't invent new color values, font sizes, or shadow tiers when a documented one already covers the role. When STYLEGUIDE.md is silent, follow the resolution order in its final section.
|
|
|
|
# Style
|
|
## Concise/Brief Non-obviosu comments ONLY
|
|
* DO NOT: be verbose, explain the obvious, walk through the code ("WHY not HOW")
|
|
* BE CONCISE. 1 LINE if possible
|
|
|
|
## Lint Rules: Do Not Disable Max Lines
|
|
|
|
NEVER add a `max-lines` disable (`eslint-disable max-lines`, `oxlint-disable max-lines`, or line-specific variants), and never add a per-file `max-lines` bump in `mobile/.oxlintrc.json`.
|
|
|
|
## File and Module Naming
|
|
|
|
Never use vague names like `helpers`, `utils`, `common`, `misc`, or `shared-stuff` for files, folders, or modules. They carry zero info and tend to become dumping grounds. Name files after what they _actually_ contain — prefer the concrete domain concept (e.g. `tab-group-state.ts`, `terminal-orphan-cleanup.ts`) over the generic role (`tabs-helpers.ts`, `terminal-utils.ts`). If you find yourself reaching for `helpers`, the file probably has more than one responsibility and should be split, or there's a better name hiding in the code that describes what the functions operate on.
|
|
|
|
## Type Declarations: Prefer `.ts` Over `.d.ts`
|
|
|
|
# Considerations
|
|
## Worktree Safety
|
|
|
|
Always use the primary working directory (the worktree) for all file reads and edits. Never follow absolute paths from subagent results that point to the main repo.
|
|
|
|
## Cross-Platform Support
|
|
|
|
Orca targets macOS, Linux, and Windows. Keep all platform-dependent behavior behind runtime checks:
|
|
|
|
- **Keyboard shortcuts**: Never hardcode `e.metaKey`. Use a platform check (`navigator.userAgent.includes('Mac')`) to pick `metaKey` on Mac and `ctrlKey` on Linux/Windows. Electron menu accelerators should use `CmdOrCtrl`.
|
|
- **Shortcut labels in UI**: Display `⌘` / `⇧` on Mac and `Ctrl+` / `Shift+` on other platforms.
|
|
- **File paths**: Use `path.join` or Electron/Node path utilities — never assume `/` or `\`.
|
|
- **Windows setup scripts**: the setup/issue-command runner is a `.cmd` batch file unless the script starts with a `#!` line — never derive that from the user's terminal-shell preference, and never launch a `.cmd` runner with a bare `cmd.exe /c` from a Git Bash pane (MSYS rewrites the `/c`). See [`docs/reference/windows-setup-shell.md`](./docs/reference/windows-setup-shell.md).
|
|
- **Linux native modules**: keep the glibc floor at Ubuntu 20.04 / glibc 2.31. A module compiled from source on a newer runner can reference symbol versions absent on the floor and crash the app on startup. See [`docs/reference/linux-glibc-compatibility.md`](./docs/reference/linux-glibc-compatibility.md); packaging fails if a bundled native binary needs newer glibc.
|
|
|
|
## SSH Use Case
|
|
|
|
All changes must consider the SSH use case. Don't assume local-only execution.
|
|
|
|
## Folder Workspace Use Case
|
|
|
|
All changes must consider folder workspaces as well as git worktrees. Don't assume every workspace is a git worktree.
|
|
|
|
## Remote Wire Compatibility
|
|
|
|
Clients and remote Orca servers update independently, so mixed versions are the normal state. Before changing anything a paired client and host exchange — RPC params, stream frames, or the content either side publishes over them — follow [`docs/reference/remote-wire-compatibility.md`](./docs/reference/remote-wire-compatibility.md). A new optional field is safe; a new stream opcode must be capability-negotiated because decoders drop unknown opcodes silently; and changing what the host publishes reaches old clients even with no wire change.
|
|
|
|
## Git Binary Compatibility
|
|
|
|
Orca runs the user's Git binary on native, WSL, and SSH hosts, which may all have different versions. Treat Git 2.25 as the core-workflow baseline and follow [`docs/reference/git-compatibility.md`](./docs/reference/git-compatibility.md).
|
|
|
|
When adding or changing a Git command:
|
|
|
|
- Check when every subcommand and option was introduced. For newer behavior, keep a baseline-compatible fallback or degrade safely.
|
|
- Use `GitCapabilityCache` with a narrow unsupported-error predicate so recurring operations do not retry a known-invalid command. Do not rely only on `git --version`; wrappers such as `simple-git` do not remove host-version differences.
|
|
- Scope capability state to the host that executes Git: native, WSL distro, SSH provider, or relay connection. Cover the first fallback, later cached calls, concurrent probes, and relevant host isolation in tests.
|
|
- Keep the real-binary compatibility contract in PR CI current. When adopting a newer Git feature, add its version boundary so the preferred command and fallback both run against representative Git releases.
|
|
- Preserve commands that begin with global Git options such as `-c` before the subcommand, including auto-maintenance suppression used by worktree-create fetches.
|
|
|
|
## Git Provider Compatibility
|
|
|
|
Source-control and review changes must consider GitLab and other supported git providers, not only GitHub. Keep provider-specific behavior behind explicit checks, and avoid GitHub-only naming for generic review concepts.
|
|
|
|
## GitHub CLI Usage
|
|
|
|
Be mindful of the user's `gh` CLI API rate limit — batch requests where possible and avoid unnecessary calls. All code, commands, and scripts must be compatible with macOS, Linux, and Windows.
|