engineering-handbook/dev-environment.md

Development Environment

Local workstation conventions for Sea Haven engineering work.

Directory Layout

~/
├── Documents/
│   ├── repositories/       # Git repos only — no loose files, scripts, or data
│   ├── working-docs/       # Cross-cutting docs, audits, drafts, reference material
│   └── ...
├── Desktop/                # Temporary workspace — nothing permanent
├── Downloads/              # Transient — delete installers after use
├── .ssh/                   # All keys, certs, PEMs, credential files (chmod 600)
└── (standard macOS dirs)

• repositories/ contains only git-tracked project directories. No loose scripts, CSVs, or data files.
• working-docs/ is for documentation that spans multiple repos — not a git repo.
• Never store secrets in repositories/ or Downloads/.
• .env files are gitignored and local-only.
• No credentials in Notion, Confluence, Slack, or other plaintext docs.

Python

Use pyenv, not Homebrew Python. Homebrew auto-upgrades Python on minor releases (3.13 → 3.14) which breaks compiled tools like SAM CLI and pip packages with C extensions.

• Global default: Python 3.12 (matches Lambda runtime — see AWS Infrastructure)
• SAM CLI installed via pip under pyenv, not via Homebrew
• pyenv init belongs in ~/.zshrc

When troubleshooting Python issues, check that pyenv is active before anything else. which python should point inside ~/.pyenv/.

Node.js

• Local: Node 24 / npm 11 (generates lockfileVersion: 3)
• Lambda: nodejs24.x, set explicitly in IaC. nodejs22.x is legacy only and never nodejs26.x; see AWS Infrastructure for the canonical rule
• Reusable workflows: always pass node-version: "24" explicitly rather than relying on a default that may change

macOS launchd and the TCC Sandbox

macOS TCC blocks launchd from reading ~/Documents/, ~/Desktop/, ~/Downloads/, and iCloud folders. A script in ~/Documents/repositories/... fails silently when launched by launchd even when chmod +x and manual invocation both succeed. The failure surfaces as LastExitStatus = 32256 (exit 126) in launchctl list.

Any launchd agent or scheduled automation must reference a script outside TCC-protected directories. Keep the source in the repo for version control, and install the runnable copy to ~/.local/bin/ or ~/Library/Application Support/<name>/. Do not grant Full Disk Access to /bin/bash.

If you edit the repo source, re-copy to the installed location — launchd reads the installed copy.

Cleanup Cadence

Cadence	Tasks
Weekly	Clear Desktop of anything older than 2 weeks
Monthly	Check Downloads for stale installers; check repositories/ for loose files; prune old VS Code extension versions
Quarterly	Audit Docker (docker system df), npm/yarn caches; review GitHub repos for archival candidates