mirror of https://github.com/Sea-Haven-Industries/engineering-handbook.git synced 2026-09-30 17:23:14 +00:00

Adam Moussa 88f7e24a23 Add Bedrock, dev-env, and Lambda template pages

Adds three handbook pages covering conventions that were previously
scattered across feedback memories or rederived from scratch each
time:

- bedrock.md captures the cross-region inference profile requirement
  for Claude 4.x Bedrock Agents and the alias-version pinning gotcha,
  plus the IAM resource pattern and the KB Docker requirement.
- dev-environment.md documents the workstation directory layout,
  pyenv/Node conventions, the macOS launchd/TCC sandbox gotcha, and
  cleanup cadence.
- lambda-template.md provides a minimal SAM scaffold that follows the
  Lambda defaults already in aws-infrastructure.md (Python 3.12,
  arm64, explicit 60-day log retention, scoped Secrets Manager
  access, module-level secret cache).

Also extends two existing pages:

- sam-project-layout.md gains a Lambda Layers section with the
  BuildMethod nesting pattern that caused a ~22-hour production
  outage when violated.
- naming-conventions.md adds a Legacy Stacks note acknowledging that
  pre-convention PascalCase stacks (SeaHavenDoorUnlockStack,
  WorkorderIngestStack) stay as-is rather than risk stack
  replacement.

2026-05-14 19:41:49 -04:00

2.8 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: 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

2.8 KiB Raw Blame History