# @upbond/sdk リリース Runbook

`@upbond/sdk`（`packages/sdk`）の初回外部リリース手順。**用意はしてあるが意図的にまだ
実行していない**作業を記録する。実行タイミングは別途人手承認で判断する。

## 1. 現状（2026-07-19 時点）

- `packages/sdk/package.json`: `"private": true`、`"version": "0.0.2"`（0.0.x 公開ライン、下記）。
- `exports` は `src` を指す（`types`/`default` とも `./src/index.ts`）。ワークスペース内の
  consumer（`packages/wallet-ui`、`packages/uat-*`）は TypeScript ソースを直接参照する。
- API リファレンスは TypeDoc → Markdown をリポジトリ内にコミット（`packages/sdk/docs/api/`）。
  ホスティングは無し。
- npm レジストリに `@upbond/sdk@0.0.1`（**プレースホルダ**、中身なし）を手動 publish 済み
  （2026-07-19）。npm Trusted Publishing の設定 UI / `npm trust` はパッケージが存在しないと
  使えないため（npm/cli#8544）。実体のあるリリースはまだ無い。

### 決定済み事項（2026-07-19 人手承認）

- **バージョン方針: 公開ラインは 0.0.x。** 1.0.0 までは破壊的変更があり得る
  （semver バンプ + `docs/24-sdk-design.md` の変更記録 + 必要なら移行ガイド、
  `docs/constitution.md` §6 の「バージョニング＋移行ガイドなしの破壊禁止」は 0.0.x でも適用）。
  完全な契約凍結は 1.0.0 から。0.0.x は semver 上すべてのバンプが破壊可能扱い
  （`^0.0.n` は 0.0.n 固定）で、この意図に一致する。
  リポジトリ内部の旧バージョン 0.2.0 / 0.3.0 は一度も publish されていないため、
  公開ラインは 0.0.2 から改番（内部 0.3.0 相当 = 公開 0.0.2）。
- **npm Trusted Publishing 設定済み**（2026-07-19、`npm trust github` で登録）:
  `upbond/wallet` リポの `release-sdk.yml`、permissions=publish、
  trust id `83970f5f-bb73-42d6-ad4c-c957a70741d2`。長期トークン不使用。
- **`@upbond/wallet-core-mpc` は SDK にバンドルする**（単独 npm 公開はしない）。
  tsup の `noExternal` に追加済み。dynamic import 経由のみで参照されるため esm の
  code-splitting で MPC スタックは別チャンクに残る（docs/24 D5 の遅延ロードは維持）。
  wallet-core-mpc のランタイム依存（`@web3auth/mpc-core-kit` 等）はバンドル内で
  external のまま。ただし SDK の package.json に直接宣言するのは provider 封じ込め
  （`scripts/check-deps.mjs`: `@web3auth/*` は wallet-core-mpc のみ）に反するため、
  正本は wallet-core-mpc の package.json の 1 箇所とし、tsup が external リストを
  そこから導出、リリースワークフローが publish 時に同じリストを SDK の
  `dependencies` へ引き上げる。
- **ドキュメントの正典 URL は `docs.upbond.io`**（Firebase Hosting、`login3-463501`）。

## 2. 初回外部リリース手順

順に実施する。(b) 以降はリリースワークフロー内で自動化し、リポジトリには commit しない。

**(a) バージョン決定 + 記録**
- ~~semver を決める~~ → **決定済み: 0.0.x 公開ライン**（上記「決定済み事項」）。公開する
  バージョンは package.json の現行 0.0.x をそのまま使う。
- `docs/24-sdk-design.md` の「変更記録（0.x）」に該当エントリを追加。破壊的変更があれば
  `docs/` に移行ガイドを添える。

**(b) publish 用に package.json を切り替え（リポジトリには commit しない）**
`.github/workflows/release-sdk.yml` の「Rewrite package.json for publish」ステップが
`npm pkg` で一時的に反映する（private / scripts / devDependencies の削除、
`@upbond/shared`・`@upbond/wallet-core-mpc` 依存の削除 = tsup が noExternal で
バンドル済み、wallet-core-mpc のランタイム依存の `dependencies` への引き上げ、
exports の dist 切替、`publishConfig.access=public`）。ワークスペース consumer は
`src` exports のままにするため、この変更を main へ commit してはならない。
手順の正典はワークフロー本体。

**(c) npm org の前提条件 → すべて完了（2026-07-19）**
- ~~`@upbond` org へのアクセス~~ → owner 権限で確認済み。
- ~~npm Trusted Publishing（OIDC）の設定~~ → プレースホルダ 0.0.1 publish 後に
  `npm trust github` で登録済み（「決定済み事項」参照）。長期トークン（`NPM_TOKEN`）不使用。
- ~~`@upbond/wallet-core-mpc` の workspace 依存~~ → **バンドル方針で解決済み**
  （2026-07-19）。ガードステップは workspace:* 依存の残存を検知するバックストップ
  として維持。

**(d) タグ push → リリースワークフロー**
- `sdk-v*` タグ（例: `sdk-v0.0.2`、package.json の version と一致必須）を push すると
  `.github/workflows/release-sdk.yml` が起動し、typecheck → test → docs 検証 → build →
  `npm publish --provenance=false` を実行する。
- publish 認証は OIDC（Trusted Publishing、トークンレス）。**provenance は付与しない**:
  sigstore の provenance は public リポジトリ限定で、private の本リポジトリからは
  レジストリが E422 で拒否する（sdk-v0.0.2 初回試行で確認、2026-07-19）。
  リポジトリを public 化した際に `--provenance` へ戻す。
- CI 内で npm を 11.5.1 以上へアップグレードするステップが必須
  （Node 22 同梱の npm 10.x は Trusted Publishing 不可）。

**(e) ドキュメントホスティング → 稼働済み（2026-07-19）**
- 正典 URL **`https://docs.upbond.io`** = Firebase Hosting サイト `upbond-sdk-docs`
  （`login3-463501`）。TypeDoc HTML（0.0.2 時点の公開 API）をデプロイ済み。
- **旧「UPBOND API Reference」（Postman ホスト）は人手承認のうえ廃止**:
  Route53（zone `Z2OWJ3556FE4D`）の CNAME を `phs.getpostman.com` →
  `upbond-sdk-docs.web.app` に差し替えた。ロールバックは CNAME を旧値に戻すだけ。
- 再デプロイ手順: TypeDoc を HTML 設定で生成し
  `firebase deploy --only hosting:upbond-sdk-docs --project login3-463501`。
  リリースワークフローには未組み込み（SDK リリース時に手動更新）。

**(f) main マージの人手承認ゲート**
- `feature → dev → main` の PR フロー（`.claude/rules/git-workflow.md`）に従う。
- `dev → main` のマージには人手承認が必要（`docs/constitution.md` / `CLAUDE.md` ハードルール）。

## 3. 公開前チェックリスト

- `/verify-spec`（spec-verifier）で `docs/00-BUILD-SPEC.md` + `docs/constitution.md` §6 に
  照合。
- **npm publish は実質不可逆**: unpublish は公開後 72 時間以内に限られ、一度使った
  バージョン番号は永久に再利用できない。バージョン決定は慎重に。
- `README.md` / `EXAMPLES.md` / API リファレンス（`packages/sdk/docs/api/`）を再生成し、
  CI が green であること。
- 公開面（`packages/sdk/src/index.ts`）に内部実装型が漏れていないこと（契約 = エクスポート
  された型・メソッド・エラー code）。

## 4. 公開後の運用メモ

- `@upbond/sdk@0.0.2` は 2026-07-19 に公開済み（`sdk-v0.0.2` タグ → workflow、
  Trusted Publishing・provenance なし）。以後のリリースは
  「version バンプ → dev → main 承認マージ → `sdk-v*` タグ push」のみ。
- `packages/sdk/package.json` は `"private": true` のまま、exports は `src` のまま維持する
  （publish 形はワークフローが生成、リポジトリには commit しない）。
- **本ローンチ（1.0.0 公開）直前に 0.0.x 全体を一括 deprecate する**（人手決定 2026-07-19。
  個別にはやらない）。2FA が必要なためメンテナが実行:
  `npm deprecate '@upbond/sdk@0.0.x' "Pre-launch versions — upgrade to 1.0.0 or later."`