mirror of
https://github.com/stablyai/orca.git
synced 2026-11-02 01:57:57 +00:00
67 lines
3.7 KiB
Markdown
67 lines
3.7 KiB
Markdown
# Useful Commands
|
|
|
|
- **Typecheck**: `pnpm tc` (or `tc:node` / `tc:cli` / `tc:web`)
|
|
- **Test**: `pnpm test [path/to/file.test.ts]`
|
|
- **Lint**: `oxlint`, or `pnpm run check:code-quality:changed` for changed files (full `pnpm lint` is slow); format with `pnpm format`
|
|
- **Design system**: `pnpm run lint:design-system` for the full renderer report (not a gate); the changed-lines gate above is what CI enforces
|
|
|
|
# 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.
|
|
|
|
# Electron UI Validation
|
|
|
|
Always run tests and agent-launched apps in the background with `ORCA_BACKGROUND_LAUNCH=1`.
|
|
Never steal monitor focus or reveal test windows: no `show()`, `showInactive()`, `bringToFront()`,
|
|
`app.focus()`, or OS activation. Use CDP screenshots of hidden renderers. Keep native-focus and visible-window tests paused on the user's desktop; run them on an isolated display or CI.
|
|
Rebuild modified launch-policy code before running an app; stale build wrappers are not safe.
|
|
|
|
Use the `$electron` skill and Playwright CDP for rendered Orca UI checks. Do not use computer-use for Orca UI validation.
|
|
|
|
# Code Style
|
|
|
|
## Reuse Before Reimplementing
|
|
|
|
Before writing new logic at any scale — a function, component, IPC channel, state store, or whole subsystem/flow — check whether an existing implementation already does the job. Extend or generalize it instead of building a parallel version.
|
|
|
|
## Avoid Comments
|
|
|
|
- Only use when code does not describe
|
|
- BE CONCISE. 1 LINE if possible (why not how)
|
|
|
|
## 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 Assertions: Prefer Checked Types
|
|
|
|
Avoid type assertions except `as const`. Unavoidable casts need a line-specific `SAFETY:` explanation:
|
|
|
|
# First Class Citizens
|
|
|
|
Every change must consider these areas:
|
|
|
|
## Cross-Platform Support
|
|
|
|
Support macOS, Linux, and Windows. Guard platform-specific behavior at runtime; use platform-aware shortcuts, paths, and existing process wrappers. Before changing platform-specific code, processes, shells, shortcuts, paths, or native modules, read [`docs/reference/cross-platform-support.md`](./docs/reference/cross-platform-support.md).
|
|
|
|
## Remote Use Case
|
|
|
|
Support remote execution as well as local. Clients and servers update independently; preserve compatibility across mixed versions.
|
|
|
|
## Mobile
|
|
|
|
Any feature should be considered for parity on mobile
|
|
|
|
## Folder Workspaces
|
|
|
|
All changes must consider folder workspaces as well as git worktrees. Don't assume every workspace is a git worktree.
|
|
|
|
# Git / GitHub
|
|
|
|
If changing code around `git`, `gh`, source-control, or review behavior read [`docs/reference/git-workflow.md`](./docs/reference/git-workflow.md).
|
|
|
|
# Tests
|
|
|
|
Avoid adding low-value tests. These might be fine for development but offer low value when checked in. [Anti-patterns](./docs/reference/test-antipatterns.md)
|