widget/receiver: payload に sourceContext(repo/branch/commit)を追加する (#96 PR-A)

[kosako]

概要

#96 のスライス PR-A。AI agent が feedback をソースコードに対応付けるための git 由来情報(sourceContext)を widget payload に載せ、receiver で検証・保存する。issue body の agent-ready 再設計は PR-B で行う。

設計(#96 で Codex と合意済み)

• init オプションが正: 埋め込み側がビルド/デプロイ時に実値を注入する。shape は { repo, branch, commit, root, buildUrl, previewUrl }(すべて optional string)
• meta タグは fallback: <meta name="patchloop:repo|branch|commit|root|build-url|preview-url"> からフィールド単位で補完
• receiver config を正本にしない: 複数 preview からの payload を受けるため、プロセス単位設定では multi-project で破綻する

変更内容

• widget/src/source-context.js(新規): resolveSourceContext(configured, doc)。6 フィールドの whitelist、trim 済み非空 string のみ採用、全滅なら null
• widget/src/index.js: DEFAULTS.sourceContext、init で一度だけ解決、buildPayload に配線。PAYLOAD_SCHEMA_VERSION 1 → 2(コメントの契約どおり shape 変更で bump)
• server/receive.js: validateFeedbackPayload に optional な sourceContext の shape 検証を追加(object・各フィールド string)。store は JSON round-trip のためスキーマ変更不要。DEFAULT_SCHEMA_VERSION は「schemaVersion 無し=旧 payload」への補完なので 1 のまま
• テスト: widget 側 5 件(option 優先・meta 補完・非 string 除外・空白除外・null)、receiver 側 2 件(保存 round-trip・shape 検証 400)
• README 日英: init オプションと payload 項目に追記
• dist/patchloop-widget.js 再ビルド

検証

• npm run check(lint + dist 同期 + 全 112 テスト)green
• E2E: 実 Chrome でテストページ(init オプションに repo/branch、meta タグに commit/preview-url)から実 receiver に送信し、option と meta のマージ結果が sqlite まで round-trip することを確認

Closes 条件は #96 の受け入れ条件 1 のみ(2 は PR-B、3 はセッション作業)なので、この PR では #96 を close しない。

🤖 Generated with Claude Code

https://claude.ai/code/session_01LRdDjwxbAAaTMwwnzipkau

[kosako]

🔍 レビュー依頼(→ Codex)

• 観点: payload 契約の拡張(widget→receiver の sourceContext 追加)。重点は
  (1) 契約整合 — widget が載せる shape と receiver 検証・README 記載のズレ、
  (2) 検証の抜け — sourceContext 経由で validation/limits を迂回できないか、
  (3) 最小差分 — PR-A スコープ(issue body 再設計 = PR-B)からの逸脱、
  (4) 既存契約の維持 — schemaVersion bump の影響(旧 payload の import / localStorage 復元)
• ランク: 🔴 must(merge 前必須)/ 🟡 should(推奨・対応は依頼元判断)/ ⚪ nit(任意)
• 結果はこの PR にコメントで返します

[kosako]

📋 レビュー結果(by Codex)

判定: ✅ merge 可(must 0 件) — 🟡 should への対応は依頼元判断

🔴 must

なし

🟡 should

• server/receive.js:1124 — receiver は sourceContext の既知 6 フィールドだけ型検証し、未知フィールドはそのまま保存される。widget 側(widget/src/source-context.js:20)は未知キーを落とし、README も 6 フィールドの optional strings と説明しているため、receiver も未知キーを reject するか strip すると契約が揃う。payload limit 自体は validateFeedbackPayload() 冒頭の enforcePayloadLimits() を通っているので迂回ではない。

依頼元の評価: 採用しない。 理由:

1. receiver の payload 検証は page / target / environment を含む全ブロックで「既知フィールドの型を検証し、未知キーは許容(サイズ・深さは enforcePayloadLimits で拘束)」という一貫したスタイルで、sourceContext だけ厳格化すると検証契約が非対称になる
2. widget と receiver のバージョンスキュー耐性のため: 将来 widget が第 7 フィールドを追加したとき、未更新の receiver が reject すると feedback がロストする(受信面の可用性が最優先)。widget 側 whitelist(送信面の junk 抑止)と receiver 側許容(受信面の前方互換)は意図的な非対称
3. 下流(issue body・agent)は既知フィールドしか読まないため、未知キーの残存に実害がない

⚪ nit

なし

レビュアーの確認事項(転記)

• widget / receiver / README(日英)の shape と fallback 優先順位は一致
• sourceContext は POST /feedback と /import の両方で validateFeedbackPayload() を通り、payload limits の迂回なし
• schemaVersion: 旧 payload 省略時の DEFAULT_SCHEMA_VERSION = 1 維持・明示 version の spread 保持を確認、v2 と旧 payload の共存に退行なし
• PR-A スコープ外(issue body 再設計)への逸脱なし
• 実行: node --test test/widget-source-context.test.js / node --check(3 ファイル)/ node scripts/build.js --check すべて成功(receiver テストは read-only sandbox の制約で実行不能、author 側の npm run check 全 112 件 green で補完)