Skip to content

Agent playbook (EDOS workspace)

Audience: Agent

Use this checklist when modifying existing projects or adding a new one. Read in order: README.md → ARCHITECTURE.md → IPC.md if touching messaging → the relevant apps/ capsule.

Before you change anything

  1. Confirm which top-level folder you are editing — this workspace is not a monorepo; do not add root-level shared packages unless maintainers agree.
  2. Open REPOS.md for run commands and npm links.
  3. If changing cross-window messaging, read IPC.md and inter-frame-messenger/src/index.ts end-to-end.
  4. If changing journal semantics, grep consumers of @howfe/elite-dangerous-event-types and update types/guards first.

Adding a new project (new top-level folder)

  1. Keep it self-contained (own package.json or build as appropriate).
  2. If it needs journal types, depend on @howfe/elite-dangerous-event-types.
  3. If it embeds or opens another window, depend on @howfe/inter-frame-messenger and extend IPC.md with new message types only after updating the enum in source.
  4. Add a capsule: docs/apps/APP_SLUG.md using the same sections as existing capsules.
  5. Update REPOS.md quick-reference table and TODO.md if you leave gaps.
  6. If the project calls third-party community HTTP APIs (SPANSH, EDSM, similar): always use the API cache server (or the same proxy pattern) — never add direct fetch / axios to those upstream URLs from the client. See ARCHITECTURE.md (third-party HTTP + design principle 5).

Changing IPC (postMessage)

  • Do not change string values of MessageTypeEnum without a coordinated release of inter-frame-messenger and all consumers (both Quasar apps at minimum).
  • Do keep send / listen allowlists symmetric with actual usage.
  • Do validate payloads with existing isEliteEvent / isStatus (or extend event-types).
  • Avoid widening allowedSenderOrigins to '*' on new code paths without a documented reason (see IPC.md).

Changing journal handling

  • Remote reader: changes in JournalWatcher.ts / StatusWatcher.ts affect deduplication, polling interval, and what gets sent — retest with surface map popup flow.
  • Surface map: readGalaxyDataFromEvents.ts and useCommanderState.ts subscribe via useJournalReader — avoid duplicate subscription bugs (singleton module state).
  • Event types: run downstream TypeScript builds after editing elite-dangerous-event-types/index.ts.

Changing API cache / external data

  • Mandatory: Community Elite Dangerous APIs are volunteer-run and usually without DDoS protection. Using the cache server is a fair-use rule: it reduces duplicate traffic and avoids putting pressure on other people’s infrastructure. All third-party API usage from apps in this ecosystem must go through the cache (or an equivalent operated the same way), not direct to SPANSH/EDSM/etc. from the browser except where a maintainer documents a rare, explicit exception.
  • Server: api-cache-server/api/src/app.ts — respect cache key and queue behavior.
  • Clients: use the fetchWithCache pattern (or the same ?url= contract against your cache base URL); do not bypass the cache for convenience.
  • Do not point the cache service at arbitrary URLs in production without understanding SSRF risk; that is separate from the fair-use rule for known community API hosts.

Bumping WebView / browser assumptions

  • File System Access API and postMessage require modern Chromium-class environments for the current design. See original-concept.md for legacy WebView caveats.

Builds / tests (current state)

Project Command (from path)
inter-frame-messenger npm run build
api-cache-server/api bun run dev / bun run start
elite-dangerous-surface-map/ui npm run lint, npm run dev, npm run build
elite-dangerous-remote-journal-reader/ui same pattern

TODO: Verify CI expectations per repo (.gitlab-ci.yml where present).

Do not

  • Convert the workspace into a monorepo “while you’re here.”
  • Add second, incompatible definitions of journal event shapes outside elite-dangerous-event-types.
  • Send journal files to api-cache-server — it is an HTTP proxy for arbitrary URLs, not a journal pipeline.
  • Call community third-party APIs directly from app code when those APIs should flow through the cache — see “Changing API cache / external data” above.