Skip to content

.lore.md

Latest commit

 

History

History
44 lines (28 loc) · 8.37 KB

.lore.md

File metadata and controls

44 lines (28 loc) · 8.37 KB
Raw

Long-term Knowledge

Decision

  • Migrated to Content Layer API: Migrated to Content Layer API in getsentry/spotlight. `packages/website/content.config.ts` is an untracked file that should NOT be committed in security/dependency bump PRs — it is intentionally excluded from those commits.

Gotcha

  • APPLE_API_KEY raw DER lacks PEM armor — breaks Xcode 26 notarytool: In getsentry/spotlight's build.yml, `jq -r .private_key` on the APPLE_API_KEY secret extracts a raw base64 DER body with no PEM header/footer/line-wrapping. Xcode 16's notarytool tolerated this, but the macOS GitHub runner rolled macOS15/Xcode16 → macOS26/Xcode26.6 on 2026-07-21; Xcode 26's notarytool rejects unarmored keys, and electron-builder's bundled @electron/notarize@2.2.1 does raw `JSON.parse` on Apple's plain-text error, masking the real cause with a SyntaxError. The key itself was valid/unexpired — issue was purely missing PEM framing. Fix (PR #1334, commit 66d991e3): wrap the body with BEGIN/END PRIVATE KEY armor + 64-col folding, idempotently (skip if already armored), in both build.yml locations that decode the key. Verified end-to-end on main via GitHub Actions run 29828172734 on macos-26-arm64/macOS 26.4 — "notarization successful" logged for both x64 and arm64 builds, DMGs produced.
  • esbuild override cap in getsentry/spotlight — resolved at 0.28.1: The pnpm override `"esbuild": ">=0.25.0 <0.28.0"` was a deliberate cap to avoid esbuild#4436 (erroring on destructuring for old targets). Trap: bumping to `>=0.28.1` looks risky because 0.28.x retained that behavior. Fix: the regression did NOT reappear in practice — website build succeeded without adding `target: "es2020"`. Override is now `"esbuild": ">=0.28.1"`, resolving Dependabot alerts #279 and #280. These alerts were merged via PR #1323 on 2026-06-16 and will auto-close without further action.
  • getsentry/spotlight E2E: body.textContent() races React hydration — use web-first nav selector instead: Trap: `body.waitFor()` then `body.textContent() !== ''` looks like a safe readiness check because the body element exists immediately. Fix: the body element is present in the SPA HTML shell before React hydrates, so a one-shot read races React's first render. Other tests pass incidentally due to `sendTestEnvelope` 500ms settle delay or explicit `waitForTimeout(1000)`. Stable readiness selector: `nav[aria-label="Navigation"]` in `TelemetrySidebar.tsx` — renders unconditionally once React mounts, independent of event data. Use a `waitForAppReady(page, timeout)` helper in `fixtures.ts` that asserts this nav locator is visible with Playwright's built-in auto-retry.
  • plist override breaks electron-builder osx-sign: Forcing `plist>=3.1.1` via pnpm overrides bumps it to v5.x, which breaks `@electron/osx-sign@1.0.5` (used by `electron-builder@24.13.3`) due to incompatible CJS `require()` and new `exports` map. Fix: remove the `plist` override and instead override `@xmldom/xmldom` directly to `>=0.8.13` (first patched 0.8.x version). This keeps `plist@3.1.0` for osx-sign compatibility while eliminating the `@xmldom/xmldom` vulnerability.
  • scripts/notarize.cjs is dead code in getsentry/spotlight: electron-builder notarizes internally via its afterSign hook using @electron/notarize; it never calls scripts/notarize.cjs. Don't assume this file is the active notarization path when debugging Apple notarization failures — check build.yml's Apple key decode/export steps and electron-builder's config instead.

Pattern

  • Security dep-bump workflow in getsentry/spotlight: Pattern for resolving Dependabot alerts in getsentry/spotlight: (1) fetch alerts via `gh api /repos/{owner}/{repo}/dependabot/alerts`; (2) plan fix in `.opencode/plans/`; (3) bump pnpm overrides in root `package.json` AND direct deps in affected `packages/*/package.json`; (4) run `pnpm install`, verify lockfile, run full `pnpm build` + `vitest run`; (5) create branch `security/deps-<descriptor>` off main, commit, push, open PR. Vite major-version overrides must be bounded (e.g. `<8`). Untracked `.opencode/` and `packages/website/content.config.ts` are intentionally excluded from commits; `.lore.md` is always staged via `git add .lore.md` alongside code changes. E2E UI test flakes are known — rerun before investigating. Playwright Chromium binary download/extraction can hang indefinitely in this environment; verify E2E fixes via CI rather than local Playwright runs.

Preference

  • Insist on empirical verification and full CI closure before declaring a fix done: The user demands rigorous, adversarial correctness review of CI/infra fixes (not style-only), requiring empirical reproduction of edge cases in an isolated scratch directory (e.g. /tmp/opencode) with throwaway test data—never touching tracked files—before merging. After merging, the user follows up explicitly to confirm the actual CI run succeeded end-to-end (not just 'job passed' but that the specific mechanism, e.g. notarization, actually executed and succeeded for all variants/architectures). The user also enforces splitting unrelated changes (e.g. dependency version bumps) into separate PRs, keeping fix PRs narrowly scoped. When assistant proposes optional/secondary improvements, the user expects them raised explicitly for a yes/no decision rather than bundled in. Always verify real production behavior (log output, not just exit codes) and keep changes atomic and reviewed with skepticism.
  • Never trust unverified fixes; demand rigorous empirical/adversarial verification before and after applying CI changes: When diagnosing and fixing CI/build issues (especially security-sensitive ones like secrets, keys, or PEM handling), the user consistently insists on: (1) empirical root-cause verification via actual reproduction (decoding keys, hexdumps, testing openssl parsing) rather than accepting a hypothesis at face value, ruling out alternatives explicitly; (2) reproducing/testing only in scratch/tmp directories, never modifying tracked files or leaking sensitive material into logs/repo; (3) after a fix is implemented, explicitly requesting a rigorous, skeptical, adversarial CORRECTNESS review (not style/cosmetic) of the exact diff, often listing specific numbered technical points to verify (e.g., shell option interactions, edge cases in text processing, idempotency, log leakage, consistency across duplicated code blocks). The assistant should proactively verify hypotheses with real evidence, avoid touching production/tracked files during investigation, and be prepared to conduct a structured, detail-oriented review pass after any fix before considering it final.
  • Secret/credential file handling: decode in /tmp/opencode only, never print, delete after use: When Burak Yigit Kaya hands over a secret (e.g. Apple API key bundle) via a file, he expects: decode/process it only under /tmp/opencode/ (never write into the repo), never read or print its contents into chat output, and delete the file once done. He prefers dropping secrets into a file for the assistant to process directly over pasting them into chat. This extends the general WIP-artifact rule [[019f7135-8af9-78ae-833c-8decd37d78b1]] specifically to sensitive credentials, where the added constraint is never surfacing the raw value in output.
  • Split unrelated version bumps into separate PRs from urgent fixes: When fixing an urgent CI bug (e.g. Apple API key PEM armoring) that also surfaces an unrelated improvement (e.g. bumping electron-builder ^24.13.3 → ^26.15.7 for legible notarization errors), keep the urgent fix scoped to its own focused PR and defer the version bump to a separate, lower-priority PR. Confirmed preference: assistant proposed the split, user acknowledged with 'continue'.