Wegent / wework

# Wework contributor guide

This directory implements the Wework desktop workbench: Electron, Vite, React, TypeScript, and the local coding runtime. Follow the repository-wide rules in `../AGENTS.md` first.

## Wework product model

Wework is a desktop workbench for organizing work and running AI coding agents.

Its main product areas are:

- **Tasks**: standalone work items that can start and continue AI coding sessions.
- **Project spaces**: business workspaces containing boards, project tasks, comments, agents, automation, and execution history.
- **Local project spaces**: stored locally and executed by local executors.
- **Cloud project spaces**: stored in the backend and accessible across devices; their AI work can run on either local or cloud executors.
- **Code workspaces**: device-owned source directories used by executions. A project space and a code workspace are related but are not the same object.
- **Executions**: individual AI runs started from tasks, project tasks, comments, or automation.
- **Sessions**: persistent Codex conversations associated with executions and continued by follow-up comments.

Do not treat task ownership, project-space storage, code-workspace location, executor location, and session lifecycle as the same dimension.

Before changing a Wework flow, identify the affected product area and trace its source object, storage owner, workspace, executor, and session lifecycle. If the requested behavior does not make these boundaries clear, ask the user before implementation.

## UI and component rules

- Before changing Wework UI or interaction behavior, read and follow [`DESIGN.md`](DESIGN.md). It is the source of truth for product-level visual, interaction, accessibility, and responsive-design decisions.
- Mobile is `<=767px`, tablet `768px–1023px`, desktop `>=1024px`. Split mobile and desktop components when layout or interaction differs materially; otherwise use responsive classes. Mobile controls must be at least `44px × 44px`.
- Follow the Codex-derived, neutral-first visual system in `DESIGN.md`: grayscale surfaces, `14px` default desktop UI text, sparse hairlines and shadows, inverse-neutral primary actions, and blue only for focus, links, or narrow selection accents. Green and teal are restricted to semantic success/addition states and must never define product chrome or default actions.
- Use the Codex component density documented in `DESIGN.md`: `30px` sidebar rows, `28px` app-shell tabs and composer actions, `16px` standard desktop icons, and `4px–8px` action-group gaps. Reuse the shared component's established size instead of inventing a local height.
- Use the shared typography scale and semantic `heading-*`, `text-chat`, and `text-code` roles. Never add arbitrary `text-[Npx]`, literal CSS `font-size`, or literal inline `fontSize` values; `pnpm lint` enforces this rule.
- Custom Markdown renderers must preserve semantic attributes supplied by the parser, such as an ordered list's `start` value.
- Preserve platform text-navigation semantics in the ProseMirror chat composer. Register only composer-specific key bindings instead of the document-level `baseKeymap`, and scope mention caret workarounds to unmodified arrow keys.
- Focus popup composers through their exact editor target; a mixed `querySelector` returns the first matching element in DOM order, not the first selector in the list. In WKWebView, keep a completely empty contenteditable position native instead of replacing it with a decoration widget so programmatic focus can start the platform text input session.
- Keep model selector controls mounted while refreshing an already-loaded model catalog. Reserve loading placeholders for the initial catalog load so background refreshes do not create blank composer actions.
- In project-board hover conversations, handle self-contained actions such as sending, retrying, answering runtime input, and loading or reverting diffs inside the popup. Actions that require workbench UI, including opening files, skills, reviews, plans, or switching the retry model, must navigate to the bound Runtime task. Never render an enabled conversation action without a real handler.

## i18n

- Use the local `@/hooks/useTranslation` wrapper for new Wework code.
- Add new copy to the appropriate Wework namespace in both `src/i18n/locales/en/` and `src/i18n/locales/zh-CN/`; register a new namespace in `src/i18n/index.ts`.

## Testing

- Before modifying code, locate and understand the tests and E2E coverage for
  the affected behavior, including its scenarios, fixtures, assertions, and
  desktop runner or checkpoint integration. Use that understanding to preserve
  existing coverage and determine the verification required by the change.

Run focused tests before committing:

```bash
pnpm --filter wework test
pnpm --filter wework test <test-file>
pnpm --filter wework exec prettier --check <changed-files>
pnpm --filter wework exec eslint <changed-files>
```

- Pass Vitest file paths and filters directly after `test`. The test runner
  also removes one leading `--` for compatibility with generated commands, so
  both `pnpm --filter wework test <test-file>` and
  `pnpm --filter wework test -- <test-file>` remain focused. When running a
  focused test, confirm the initial collection output matches the requested
  files and stop the run immediately if it starts collecting unrelated tests.

E2E tests use real backend requests. Do not skip, silently fail, or replace a failing integration with frontend mocks.

- Design verification cases as a QA test plan before running them. For every changed behavior, cover the preconditions, environment and test data, exact steps, expected results, negative and recovery paths, and cleanup. Record the actual result and retain reproducible evidence for failures and critical-path success.
- Changes to a core user flow must add or update automated E2E regression coverage in the same change. Treat task creation and launch, agent interaction, local-runtime lifecycle, permissions, and failure recovery as core flows when they are affected.
- Add Wework E2E regression cases under `e2e/desktop/` and integrate them with the existing desktop runner so the GitHub desktop E2E jobs execute them. Do not place desktop regressions behind standalone local-only entry points.
- Reuse the existing `e2e:desktop` command and its established CI variants. Do not add a package script or GitHub Actions command for each scenario; extend the desktop runner or its scenario discovery instead. Add a new command only when the test requires a genuinely different CI environment or job boundary.
- Register long main-runner sections in the ordered desktop checkpoint list. `--segment <checkpoint>` must run that checkpoint alone after common bootstrap; `--from-segment <checkpoint>` must run it and every later checkpoint. Each checkpoint must create its own minimal fixtures when an earlier checkpoint is skipped, and must never silently rely on task IDs, model state, or UI state produced only by a previous checkpoint.
- Ordinary desktop E2E UI actions and waits use the shared 10-second step timeout. Pass an explicit `timeoutMs` only for a genuinely slow operation such as application startup, workbench reconnection, or a deliberately held model response; do not restore a broad 120-second default.
- In virtualized content, do not rely on test-added DOM attributes across scrolling or rendering updates. Locate the element with stable product selectors and text first, wait for layout to settle, then add any temporary marker needed by later assertions.
- E2E coverage complements, but never replaces, verification in the real Electron application.

## Real desktop verification

Any Wework UI, Electron host command, local-runtime, IPC, or desktop integration behavior change requires isolated real-Electron verification in addition to unit and E2E tests. A browser-only or mocked run is not sufficient. Use `scripts/ai-verify.mjs`; do not drive a personal Wework window, external Chrome, or browser plug-ins.

```bash
pnpm --filter wework ai:verify start
pnpm --filter wework ai:verify start --packaged true
pnpm --filter wework ai:verify snapshot --session <session-path>
pnpm --filter wework ai:verify debug --session <session-path>
pnpm --filter wework ai:verify active-element --session <session-path>
pnpm --filter wework ai:verify click --session <session-path> --selector '[data-testid="..."]'
pnpm --filter wework ai:verify click-at --session <session-path> --value '{"x":640,"y":360}'
pnpm --filter wework ai:verify click-then-macrotask --session <session-path> --selector '[data-testid="..."]' --target '[data-testid="..."]'
pnpm --filter wework ai:verify drag --session <session-path> --selector '[data-testid="..."]' --target '[data-testid="..."]'
pnpm --filter wework ai:verify fill --session <session-path> --selector '[data-testid="..."]' --value '...'
pnpm --filter wework ai:verify hover --session <session-path> --selector '[data-testid="..."]'
pnpm --filter wework ai:verify pointer-move --session <session-path> --selector 'body'
pnpm --filter wework ai:verify seed-local-project --session <session-path> --value '{"name":"AI Verify","path":"/absolute/workspace/path"}'
pnpm --filter wework ai:verify reload --session <session-path>
pnpm --filter wework ai:verify wait-for --session <session-path> --selector 'body' --text '<expected post-reload text>'
pnpm --filter wework ai:verify wait-for --session <session-path> --selector '[data-testid="..."]' --text '...'
pnpm --filter wework ai:verify capture --session <session-path> --output <png-path>
pnpm --filter wework ai:verify request-close --session <session-path>
pnpm --filter wework ai:verify close-to-tray --session <session-path>
pnpm --filter wework ai:verify stop --session <session-path>
```

- `start` prepares and launches Electron directly from the source application directory, waits for the WebView, creates an isolated executor home, links local Codex authentication only for that session, and gives the app its own stdio-managed executor child. `start --packaged true` builds the app bundle before launching it; use that mode only when validating packaged resources or macOS application identity.
- Use `start --codex-home-initialization true` to verify the first-run Codex migration flow with a session-local native Codex home and synthetic authentication; it does not read or modify personal Codex credentials.
- Session files and credentials are secrets: never print their contents. Always stop the session; it removes the auth link and terminates the isolated process group.
- Begin with `snapshot`, use existing `data-testid` selectors, and assert a visible text or stable element after each critical action.
- Use `seed-local-project` only to establish an isolated local-project fixture when a native folder picker would block automation. `reload` waits for the new control client to reconnect; always follow it with `wait-for` so the expected post-reload UI state is asserted.
- Prefer selector-based actions. Use `click-at` only for visible controls that cannot expose a stable selector, including controls inside open shadow roots, and retain a screenshot showing the target coordinates.
- Execute the complete QA test plan in the isolated Electron session, including the primary path, relevant boundary and error cases, and recovery. Document the environment, cases run, actual results, and evidence in the change handoff or pull request.
- Use `capture` after the final assertion when a visual verification artifact is required. It renders the current WebView without macOS screen-recording permission.
- Use `request-close` to exercise the native main-window close request and its close-to-tray preference or confirmation flow.
- Use `close-to-tray` only for window-lifecycle verification. It hides the controlled window while preserving its renderer and the isolated Electron process so native reopen behavior can be tested.
- On failure, inspect `app.log`, `executor.log`, and Electron host logs under `test-results/ai-verify/`; do not silently downgrade to mocked verification.

## Local runtime boundaries

- Keep the local runtime and desktop UI isolated from a developer's normal Codex home. Do not copy or log credentials.
- Local coding tasks and desktop workbench behavior must remain functional when the cloud connection is unavailable; do not hide primary-path state or synchronization bugs behind fallback behavior.
- Keep project-space conversation semantics identical for cloud and local projects. Each top-level activity comment owns one independent executor session; replies inside that activity thread continue the owning session; a new top-level comment starts a new session. Cloud and local implementations may differ in storage and dispatch, but must not differ in these user-visible session boundaries.