Skip to content

developer_onboarding.md

Latest commit

 

History

History
120 lines (86 loc) · 3.29 KB

developer_onboarding.md

File metadata and controls

120 lines (86 loc) · 3.29 KB

Developer Onboarding

This document is for developers working on apps/server, apps/web, or the shared packages.

Repository orientation

apps/server      local API server, runner, policy, scheduler, Telegram
apps/web         mobile-first browser UI with PWA foundation
packages/api-types      shared domain types
packages/policy-engine  rule evaluation only
docs/            product and operations documentation
examples/        policy and later integration examples

Recommended start

npm run setup:quick

Preferred onboarding path on Windows:

  • creates .env.local.ps1
  • installs dependencies
  • installs Playwright Chromium
  • builds the repo

On macOS/Linux, the same quick path works when pwsh is installed. Without a PowerShell runtime, use the manual path below.

Full manual path:

npm install
npx playwright install --with-deps chromium
npm run typecheck
npm run lint
npm run build
npm run test:run

For local feature work, stub mode is usually the fastest:

. .\.env.local.ps1
$env:CC_CODEX_RUNNER_MODE="stub"
$env:CC_API_TOKEN="replace-with-a-strong-token"
npm run start --workspace @codex-command-center/server

Development flow

  1. Identify the feature or bug in the correct layer.
  2. Update shared types first when API or domain types change.
  3. Update server logic and persistence.
  4. Change web app code only against the real API contract, not imagined data shapes.
  5. Extend regression or browser tests when runtime paths are affected.
  6. Run typecheck, lint, build, and test:run locally to pass.

Where changes belong

New API fields or new status values

  • packages/api-types/src/index.ts
  • then align server persistence, HTTP routes, and web types

New policy rule

  • packages/policy-engine/src/index.ts for pure rule evaluation
  • apps/server/src/policy.ts for persistence, approval creation, and expiry behavior
  • matching regression tests in apps/server/test/regression.test.mjs

New run or session path

  • apps/server/src/runner.ts
  • apps/server/src/http.ts
  • possibly apps/server/src/automation.ts

New web view or mobile interaction

  • apps/web/src/main.ts
  • apps/web/src/api.ts
  • apps/web/src/styles.css
  • for PWA behavior, also apps/web/sw.js and apps/web/e2e/pwa.spec.mjs

Testing strategy

Server side:

  • regression tests in apps/server/test/regression.test.mjs
  • focus on real HTTP and runtime paths

Browser side:

  • Playwright in apps/web/e2e/pwa.spec.mjs
  • currently focused especially on service worker and PWA behavior

Required checks before review:

  • npm run typecheck
  • npm run lint
  • npm run build
  • npm run test:run

Practical guidance

  • Always test policy and approval paths as runtime behavior, not only static checks
  • Model API errors explicitly as 400, 401, 404, 409, or 202
  • with Telegram, distinguish hard secret errors from silently ignored unauthorized chats
  • never deliver API data from the service worker as cache-first
  • do not let desktop assumptions override mobile UX

Relevant docs