mirror of
https://github.com/Sea-Haven-Industries/engineering-handbook.git
synced 2026-09-30 06:53:15 +00:00
651dff5dd3
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.
55 lines
2.8 KiB
Markdown
55 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 |
|