mirror of https://github.com/Sea-Haven-Industries/engineering-handbook.git synced 2026-09-30 05:43:15 +00:00

docs(lambda): unify the node runtime rule on 24.x

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.

2026-07-28 19:42:53 -04:00

2.9 KiB

Raw Blame History

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" (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

2.9 KiB Raw Blame History