stitch-sdk-pipeline

Stitch SDK パイプライン

このスキルは、MCP ツールのスキーマ取得から、テストおよび検証済みのパッケージの公開まで、SDK 生成パイプライン全体を調整します。次の場合に使用します。

• Stitch MCP サーバーでツールが追加または変更された場合
• SDK を一から再生成する必要がある場合
• パイプラインが正常に動作しているか確認したい場合

重要

エージェントの判断が必要なのはステージ 2 のみです。 それ以外のステージはすべて決定的なスクリプトです。ステージ 2 では、stitch-sdk-domain-design スキルを使用してください。

---

前提条件

• STITCH_API_KEY 環境変数が設定されていること
• bun がインストールされていること
• 作業ディレクトリ：プロジェクトのルート（stitch-sdk/）

---

パイプラインの各ステージ

ステージ 1：ツールスキーマの取得 🤖

// turbo
npm run capture

Stitch MCP サーバーに接続し、tools/list を呼び出して、生のスキーマを packages/sdk/generated/tools-manifest.json に書き込みます。stitch-sdk.lock のマニフェストセクションを更新します。

出力：packages/sdk/generated/tools-manifest.json（すべてのツールの inputSchema と outputSchema を含みます）

省略する場合：tools-manifest.json がすでに最新で、サーバー側に変更がない場合。

---

ステージ 2：ドメイン設計 🧠（エージェント）

このステージでは stitch-sdk-domain-design スキルを使用してください。

tools-manifest.json を読み込み、packages/sdk/generated/domain-map.json を編集して、ツール → クラス → メソッドの対応を定義します。

このステージで決定する項目：

• 各ツールをどのクラスが所有するか
• 引数のルーティングルール（self、param、computed、selfArray）
• レスポンスの射影パス
• メソッドで構築時のレスポンスデータをキャッシュするかどうか

入力：tools-manifest.json + scripts/ir-schema.ts（正規の IR コントラクト） 出力：packages/sdk/generated/domain-map.json

省略する場合：domain-map.json にすでに正しいバインディングがあり、ir-schema.ts または generate-sdk.ts のみを変更した場合。

---

ステージ 3：TypeScript の生成 🤖

// turbo
npm run generate

IR（Zod スキーマ）と各射影（outputSchema に対して）を検証し、ts-morph を使って packages/sdk/generated/src/ に TypeScript ファイルを生成します。

出力：packages/sdk/generated/src/*.ts + 更新された stitch-sdk.lock

射影エラーが発生した場合は、ステージ 2 に戻り、domain-map.json を修正してください。

---

ステージ 4：ビルド 🤖

// turbo
npm run build

TypeScript のコンパイル：packages/sdk/ → packages/sdk/dist/。

---

ステージ 5：ユニットテスト 🤖

// turbo
npm run test

コアユニットテスト（vitest）を実行します。callTool をモックし、生成されたメソッドシグネチャ、キャッシュ、エラー処理を検証します。

---

ステージ 6：スクリプトテスト 🤖

// turbo
npm run test:scripts

bun:test を使って、コントラクトテスト（IR スキーマの受け入れ／拒否）とロジックテスト（式ビルダー）を実行します。

---

ステージ 7：E2E テスト 🤖

npm run test:e2e

ビルド済みパッケージを使って、ライブ API テストを実行します。STITCH_API_KEY（AI SDK テストには GEMINI_API_KEY も）が必要です。テストスイートは 2 つあります。

• live.test.ts — SDK を直接呼び出し、プロジェクトを作成し、画面を生成して、レスポンスを検証します。
• ai-sdk-e2e.test.ts — stitchTools() を介した AI SDK 統合です。Gemini が自律的に Stitch ツールを呼び出し、デザインを生成し、HTML + Tailwind 設定を抽出して、モジュール式 React コンポーネントを生成します。SWC で検証した後、.stitch/preview/ に Vite プレビューアプリのひな形を作成します。

---

ステージ 8：ロックの検証 🤖

// turbo
npm run validate:generated

stitch-sdk.lock のハッシュが実際に生成されたファイルと一致するか検証します。生成ファイルを手動で編集したり、再生成を忘れたりしたことによるずれを検出します。

重要

必ずステージ 3（生成）の後に実行してください。取得（ステージ 1）の後、再生成せずに検証を実行すると、マニフェストのハッシュが変わっているため、ハッシュが一致しません。

ステージ 9：スキルの監査 🧠（エージェント）

パイプラインが正常に完了したら、エージェントのスキルが最新かどうかを監査します。現在の信頼できる情報源を確認し、古くなったメソッド、引数、または例を参照しているスキルを更新してください。

入力：

• packages/sdk/src/index.ts（公開 API）
• packages/sdk/generated/src/ 内の生成されたクラスファイル
• packages/sdk/src/spec/errors.ts（エラーコード）
• packages/sdk/src/spec/client.ts（設定スキーマ）

監査するスキル（優先順位順）：

1. stitch-sdk-usage — 変更頻度が最も高く、具体的なメソッドやコンストラクターのシグネチャを参照しています
2. stitch-sdk-readme — stitchTools()、toolDefinitions、AI SDK の統合例を必ず説明してください
3. stitch-sdk-development — キャッシュの例が現在のドメインマップのパターンに一致していることを確認してください
4. stitch-sdk-domain-design — キャッシュのセクションにあるコード例を確認してください

監査をスキップするスキル：stitch-sdk-pipeline（自己参照）、red-green-yellow（汎用的な手法）。

確認する項目：

• コード例にあるすべてのメソッド名が、それぞれのクラスに存在すること
• 例にあるすべてのインポートが、index.ts のエクスポートと一致すること
• コンストラクターのシグネチャが実際のコンストラクターと一致すること
• 設定フィールドが StitchConfigSchema と一致すること
• エラーコードが StitchErrorCode と一致すること

スキップする条件：インフラストラクチャのコード（packages/sdk/src/client.ts、packages/sdk/src/proxy/）のみが変更され、公開 API に変更がない場合。

---

クイックリファレンス

パイプライン全体（スクリプトのステージのみ）

npm run pipeline

ステージ 1 → 3 → 4 → 5 を順番に実行します。ステージ 2（エージェント）、ステージ 7（e2e）、ステージ 9（スキルの監査）は含まれません。

特定のステージから開始する場合

シナリオ	開始ステージ
MCP サーバーに新しいツールを追加した	ステージ 1
ツールをメソッドにマッピングする方法を変更したい	ステージ 2
ir-schema.ts または generate-sdk.ts を変更した	ステージ 3
packages/sdk/src/ 内のコード（クライアント、エラー）を変更した	ステージ 4
すべてが正常に動作することを確認したいだけの場合	ステージ 5
AI SDK ツールアダプターまたはツール定義を変更した	ステージ 5
公開 API を変更した	ステージ 9

主要なファイル

ファイル	場所	役割
tools-manifest.json	packages/sdk/generated/	生の MCP ツールスキーマ（ステージ 1 の出力）
domain-map.json	packages/sdk/generated/	IR：ツール → クラス → メソッドのマッピング（ステージ 2 の出力）
tool-definitions.ts	packages/sdk/generated/src/	AI SDK 用に生成された JSON Schema ツール定義
tools-adapter.ts	packages/sdk/src/	stitchTools() — AI SDK v6 アダプター（@google/stitch-sdk/ai 経由でインポート）
ir-schema.ts	scripts/	有効な IR 構造を定義する Zod スキーマ
tool-schema.ts	scripts/	JSON Schema 用の TypeScript 型
generate-sdk.ts	scripts/	ts-morph によるコード生成（ステージ 3）
stitch-sdk.lock	packages/sdk/generated/	ドリフト検出用の整合性ハッシュ
stitch-html.ts	packages/sdk/test/helpers/	Stitch HTML パーサー（Tailwind の設定とフォントの抽出）
component-validator.ts	packages/sdk/test/helpers/	生成された React コンポーネント用の SWC AST バリデーター