notion-sync-migration

name	notion-sync-migration
description	@lacolaco/notion-syncのメジャーバージョンアップを実行する。notion-syncのアップグレード、マイグレーション、バージョンアップと言われた時に使用する。新バージョンが未公開の場合はポーリングで待機する。
allowed-tools	["Read","Edit","Write","Bash(pnpm add:*)","Bash(pnpm format:*)","Bash(pnpm notion-sync:*)","Bash(npx tsc:*)","Bash(npm view:*)","Bash(git:*)","Bash(gh:*)","Bash(sleep:*)"]

notion-sync Migration

@lacolaco/notion-syncのメジャーバージョンアップを安全に実行する。

原則

旧バージョンの知識を全て捨てろ。 新バージョンのCHANGELOGとREADMEを全文読むまで、コード変更を一切行うな。

手順

1. 現状確認

grep "notion-sync" package.json

現在のバージョンと、対象バージョンを特定する。

2. 新バージョンの取得

対象バージョンがnpmに公開済みか確認する。

npm view @lacolaco/notion-sync version

未公開の場合、バックグラウンドで30秒間隔でポーリングする。

while true; do
  version=$(npm view @lacolaco/notion-sync version 2>/dev/null)
  if [[ "$version" == <target-major>.* ]]; then
    echo "published: $version"
    break
  fi
  sleep 30
done

3. インストール

pnpm add -D @lacolaco/notion-sync@<version>

4. ドキュメント精読（省略禁止）

インストール後、以下を全文Readする。grepでの部分検索は精読の代替にならない。

1. node_modules/@lacolaco/notion-sync/CHANGELOG.md — Breaking Changesを全て把握
2. node_modules/@lacolaco/notion-sync/README.md — 新APIの仕様とMigration Guideを把握

Breaking Changesの一覧を列挙し、現在のコード（tools/notion-sync/main.ts）への影響を対応付けてからコード変更に着手する。

5. コード変更

tools/notion-sync/main.tsを修正する。

変更時の注意:

• Migration Guideの Before/After に従う
• 型パラメータの追加など、Breaking Change以外の改善も適用する
• 不要になった型アサーション（asキャスト）は削除する
• 消費者コードが明示的に抽出しているフィールドは、ライブラリ内部が同じ値を返す場合でも削除しない。消費者の意図的な依存境界を尊重する

6. 検証

以下を全て通過させる。

npx tsc --noEmit -p tools/tsconfig.json
pnpm notion-sync --dry-run
pnpm format

dry-runの出力を確認し、queryFilterやmetadata生成が正しく動作していることを検証する。 --mode all を付与した二重検証で queryFilter の動作（取得件数）を裏取りすると信頼度が上がる。

7. コミット・PR

通常のpr-lifecycleスキルに従う。