mirror of
https://github.com/Sea-Haven-Industries/engineering-handbook.git
synced 2026-09-30 08:03:16 +00:00
Adam Moussa
670336506f
The three pages disagreed: two listed Node 24.x while the workstation page still allowed 22.x or 24.x, and none said anything about 26.x. State the rule once under Lambda defaults (24.x standard, 22.x legacy only until the 2027-04-30 deprecation, never 26.x) and have the other two pages defer to it.
55 lines
2.9 KiB
Markdown
55 lines
2.9 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: `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"` (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 |
|