mirror of
https://github.com/Sea-Haven-Industries/engineering-handbook.git
synced 2026-09-30 17:23:14 +00:00
56 lines
2.8 KiB
Markdown
56 lines
2.8 KiB
Markdown
|
# 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: Node 22.x or 24.x (set explicitly in IaC)
|
||
|
|
- Reusable workflows: always pass `node-version: "24"` (the default is 22 / npm 10, which can fail `npm ci` on npm 11 lockfiles)
|
||
|
|
|
||
|
|
## 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 |
|