stitch-sdk-bug-bash

Stitch SDK バグバッシュ

このスキルでは、実際の API キーを使って Stitch SDK のバグを見つけるためのフレームワークと手順を説明します。標準的な機能上のエッジケースや、通常の成功パターンを超えた厄介な状況を調べる方法を案内します。

---

心構え：敵対的な探索

このスキルを使うときは、SDK が動作することを確認するだけでなく、壊してみてください！

• 無効なパラメーターや境界値のパラメーターを渡します。
• 削除済みまたは古いハンドルに対して操作を試みます。
• 可能であれば、予期しない API レスポンスをシミュレートするか、プロジェクションが失敗する可能性のあるエッジケースを探します。

---

対象領域

1. ルートと初期化（Stitch）

• 設定なし：STITCH_API_KEY が存在する場合、明示的な設定なしでシングルトンが動作することを確認します。
• 無効な設定：空の API キーまたは無効なベース URL を StitchToolClient に渡し、最初の呼び出しが汎用的なノイズエラーではなく、明確な認証エラーまたは接続エラーで失敗することを確認します。

2. プロジェクトのライフサイクル（Project）

• ハンドルの作成：stitch.project('invalid-id') が例外をスローしない（遅延インスタンス化）ことを確認し、最初の呼び出しが安全に失敗することを確認します。
• ファクトリーと API：ファクトリー経由でプロジェクトハンドルを作成しても API 呼び出しが発生せず、project.listScreens() のようなメソッドを呼び出すと発生することを確認します。

3. 画面のライフサイクル（Screen）

• 引き継ぎ：Project.generate() のプロパティが、2 回目の取得なしで、返された Screen インスタンスに正しく設定されることを確認します。
• プロジェクションにおける null 安全性：空の配列や省略可能なフィールドが欠落した値を返すツールやシナリオをテストします。SDK のハンドルが null のプロパティへのアクセスでクラッシュせず、undefined または空の配列として処理することを確認します！

4. デザインシステム（DesignSystem）

• 適用：デザインシステムを作成し、画面のリストに適用します。リストが空または無効な場合、SDK が適切に失敗することを確認します！
• ハンドル：project.designSystem('ds-id') が projectId を正しく受け取り、ds.apply(...) などの呼び出しに注入することを確認します。

---

厄介な状況のマトリックス（標準的な機能上のエッジケース）

シナリオ	試すこと	期待される動作
古いハンドル	画面を作成し、プロジェクトを削除してから、画面ハンドルの編集を試みます。	リソースが見つからないことを示す明確な API エラーが StitchError にラップされます。
空のプロンプト	project.generate('') または空白文字のみで呼び出します。	安全に拒否されるか、明確な API エラーが返されます。コード生成でクラッシュしません。
null に対するプロジェクション	期待されるプロジェクションフィールドを含まないレスポンスを返す API 呼び出しを強制します（シミュレートできる場合、またはそのようなツールのフォールバックケースを見つけられる場合）。	SDK はオプショナルチェーン（例：raw?.prop）を使用し、TypeError: cannot read property of undefined をスローせずに undefined を返します。
巨大な配列	何百もの画面 ID を ds.apply() に渡します。	ペイロードの上限に適切に対処できるか、明確なメッセージとともに失敗するかを確認します。

診断時の注意事項

• テスト呼び出しは必ず try/catch で囲んでください。
• エラーを記録し、error.code または error.name を調べて、それが StitchError か一般的な未加工エラーかを確認してください。
• 実行時に未加工の TypeError または「cannot read property of undefined」が発生した場合、SDK のプロジェクションロジックに最優先で対応すべきバグがあります！

---

テストテンプレート：完全なワークフローの Bash

簡単なエンドツーエンドの Bash セッションを実行するには、このテンプレートを使用してください。

import { stitch } from "@google/stitch-sdk";

async function bash() {
  const apiKey = process.env.STITCH_API_KEY;
  if (!apiKey) throw new Error("STITCH_API_KEY is required");

  console.log("🚀 Starting Bug Bash...");

  let project;
  try {
    // 1. Create a fresh project
    project = await stitch.createProject({
      displayName: `Bug Bash ${new Date().toISOString()}`,
    });
    console.log(`✓ Created Project: ${project.id}`);

    // 2. Try to break generate with empty prompt
    try {
      await project.generate({ prompt: "" });
      console.log("✗ BUG: Generate with empty prompt should have failed!");
    } catch (e) {
      console.log("✓ Generate with empty prompt failed safely as expected.");
    }

    // 3. Create a design system
    const ds = await project.createDesignSystem({
      name: "Bash Style",
      variables: { primaryColor: "#ff0000" },
    });
    console.log(`✓ Created Design System: ${ds.id}`);

    // 4. List screens (should be empty)
    const screens = await project.listScreens();
    console.log(`✓ Listed screens: found ${screens.length}`);

    // 5. Apply design system to empty list
    try {
      await ds.apply({ selectedScreenIds: [] });
      console.log("✓ Applied design system to empty list (handled).");
    } catch (e) {
      console.log("✗ Did applying to empty list fail? Inspect error.");
    }
  } catch (error) {
    console.error("💥 Bash failed with error:", error);
  } finally {
    // 6. Cleanup
    if (project) {
      console.log(`🧹 Cleaning up project ${project.id}...`);
      // Assuming we have a deleteProject binding or we just leave it if not available
      // await project.delete();
    }
  }
}

bash();