evOo-local/CONTRIBUTING.md

Contributing to evOo

Thanks for helping improve evOo. Keep changes focused and testable.

Run locally

Follow the source checkout setup for prerequisites, required secrets, and startup commands.

Checks before you open a PR

Command	When to run
pnpm test	Default. Units, properties, and in-process contracts. Scripted runtime, fake sandbox, in-memory wakeup — no live connector or model-provider calls.
pnpm test:integration	Postgres via Testcontainers: product journeys, authorization, executor lifecycle, Graphile / LISTEN/NOTIFY. Needs Docker.
pnpm test:e2e	Playwright against the emulated API. Needs Docker.
pnpm test:topology	Local product-path smoke: Docker computer + Graphile worker recovery. Needs Docker. Not PR CI.
pnpm test:canary	Live provider canaries. Needs keys. Not PR CI.
pnpm test:pi	Real Pi against a local HTTP model fixture: streaming, tool round trips, failures and cancellation. No keys.
pnpm test:computer-replay	Real Pi and Docker Chromium against a local model fixture. Needs the computer image; no keys or Electron windows.
pnpm test:evals --list	List agent-quality cases. Add --live and a model connection to measure repeated real-model task success.
pnpm test:computer	Real vision model + E2B desktop. Needs keys; see computer verification. Not PR CI.
pnpm check	TypeScript (tsc) across the monorepo.
pnpm lint	Biome lint and format check.

CI runs pnpm lint, pnpm check, production builds (including Electron preload smoke), pnpm test, pnpm test:integration, and pnpm test:e2e on every PR.

Adding a UI language

The web and Electron-hosted UI use Lingui catalogs. To add a locale, register it in apps/web/lingui.config.ts, apps/web/src/lib/ui-locale.ts, and apps/web/src/lib/i18n.ts, then run pnpm --filter @rakazo/web intl:extract, fill the new apps/web/src/locales/<locale>/messages.po catalog, and validate it with pnpm --filter @rakazo/web intl:compile. Keep message IDs, placeholders, JSX markers, and ICU plural branches intact; do not commit generated *.js/*.mjs catalog files.

Expo mobile has its own catalog and locale registry. Add the locale to apps/mobile/lib/ui-locale.ts, add apps/mobile/lib/locales/<locale>.ts, and register the catalog in apps/mobile/lib/i18n.ts. Web PO entries do not translate mobile automatically. Update the locale unit tests and a UI E2E scenario for each supported surface. The marketing homepage in apps/www and the native Electron setup window have separate localization paths; scope and test those changes explicitly instead of assuming the web catalog covers them.

See agent verification for the distinction between deterministic execution tests, computer replay, and real-model quality evals.

Optional live-provider checks

The default Playwright suite uses the fake sandbox. To run the same scripted-agent suite against real computers, set the matching E2B_API_KEY, DAYTONA_API_KEY, or BOX_API_KEY and choose a provider:

pnpm test:e2e -- --sandbox=e2b
pnpm test:e2e -- --sandbox=daytona
pnpm test:e2e -- --sandbox=box

The Playwright workflow also accepts these providers through its manual Sandbox provider input. These runs provision real machines and destroy them after the suite. Automatic runs use fake. For the separate real-model desktop acceptance test, see computer verification.

Secrets and configuration

• Never commit .env files or secrets.
• Never paste API keys, tokens, or passwords in issues or PRs.
• Use placeholders in examples (your-openrouter-key, etc.).

The product path is Pi + Docker + Graphile. Emulator settings (AGENT_RUNTIME=scripted, SANDBOX_PROVIDER=fake, WAKEUP_DRIVER=memory) are for tests only.

Integrations can use Composio or Pipedream Connect as optional managed app catalogs. Users can also install HTTPS MCP servers (including Treg) and bounded OpenAPI tool sources. Connector tests must stay deterministic and offline. Never put connector credentials in capability config, fixtures, logs, or snapshots; use the encrypted secret store and fake placeholders.

Pull requests

• Keep PRs small and easy to review.
• Target the main branch.
• Describe why the change is needed, what changed, and how you tested (e.g. pnpm test, manual steps).
• Link related issues when applicable.

Contact

Address	Use for
GitHub private advisory / cynarAI	Vulnerabilities only — see SECURITY.md
cynarAI	User and support questions
cynarAI	Maintainer