mirror of https://github.com/stablyai/orca.git synced 2026-10-21 08:03:33 +00:00

Files

T

Jinwoo-H b0a8401265 test(remote-runtime): run an old client and an old server against current code

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.

2026-08-05 04:25:03 -04:00

5.5 KiB

Raw Permalink Blame History

Design System

All UI work — layout, color, typography, spacing, component selection, UX behavior — must follow 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.
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; 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. 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.

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.

5.5 KiB Raw Permalink Blame History