Skip to content
This repository was archived by the owner on Dec 2, 2025. It is now read-only.

Latest commit

 

History

History
59 lines (51 loc) · 3.03 KB

AGENTS.md

File metadata and controls

59 lines (51 loc) · 3.03 KB

Codex Agent Operating Guide

Mission Brief

  • Maintain Forward Email specific overrides for the SnappyMail clone that lives in mail/.
  • Keep the mail/ submodule pristine; apply branding through root-level overrides only.
  • Deliver reproducible builds via ./scripts/build.sh, and validate changes with the provided Docker/PHP tooling.

Repo Orientation

  • mail/ → git submodule to forwardemail/mail (clean SnappyMail). Treat as read-only.
  • dist/ → build output (gitignored). Generated by scripts; never hand-edit.
  • plugins/, themes/, configs/ → authoritative sources for Forward Email customizations.
  • scripts/ → automation (build.sh, clean.sh, update-snappymail.sh).
  • docker/ → local-only Docker Compose stack (SnappyMail + Redis).

First-Time Setup

git submodule update --init --recursive          # pull SnappyMail clone
cd mail && npm install && npx gulp && cd ..      # compile SnappyMail assets
chmod +x scripts/*.sh
./scripts/build.sh                                # sync overrides into mail/

Day-to-Day Workflow

  1. Edit files only under plugins/, themes/, or configs/.
  2. Run ./scripts/build.sh after every change to repopulate mail/ with overrides.
  3. For local smoke tests:
    • Docker: docker-compose -f docker/docker-compose.yml up (preferred).
    • PHP: cd dist && php -S localhost:8000 (Redis unavailable).
  4. Inspect logs with docker logs -f snappymail-local-dev and validate Redis via docker exec -it snappymail-redis-dev redis-cli ping.

Testing Checklist

  • Forward Email theme renders on http://localhost:8080.
  • All three plugins (ForwardEmail, Redis Ephemeral Sessions, Client IP Passthrough) appear and enable in admin (/?admin).
  • Redis connection test succeeds (use provided JSON action or redis-cli).
  • Sessions persist in Redis and respect TTL.
  • No errors in container logs or SnappyMail UI.

Deployment Handover

  • Production rollout is orchestrated from the forwardemail/forwardemail.net monorepo via Ansible.
  • Ensure ./scripts/build.sh has been run before handing off.
  • Standard flow:
    1. Commit and push changes here.
    2. In forwardemail.net, pull latest mail-overrides.
    3. Run ansible-playbook ansible/playbooks/deploy-webmail.yml (build + rsync + permissions).

Dos and Don'ts

  • Do keep mail/ and dist/ free of manual edits.
  • Do regenerate builds after modifying overrides or updating the SnappyMail submodule.
  • Do coordinate SnappyMail version bumps via scripts/update-snappymail.sh and document in commit messages.
  • Don't commit Docker build artifacts or local configuration overrides.
  • Don't bypass the build script when preparing for deployment; Ansible relies on its output.

Reference Material

  • README.md → overview, architecture, workflows.
  • QUICKSTART.md → five-minute setup and command snippets.
  • SETUP.md → integration with the main monorepo.
  • ARCHITECTURE.md → multi-layer git/submodule model.
  • TESTING.md → exhaustive local testing + troubleshooting.
  • SUMMARY.md → high-level recap and next steps.