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](aws-infrastructure.md#lambda-defaults))
- 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](aws-infrastructure.md#node-runtime) 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 |