Stitch SDK Bug Bash Agent Skill

Stitch SDK Bug Bash

This skill provides a framework and instructions for finding bugs in the Stitch SDK using a real API key. It guides you through exploring standard functional edge cases and tricky situations beyond the golden path.

The Mindset: Adversarial Exploration

When using this skill, do not just verify that the SDK works. Try to break it!

• Pass invalid or boundary parameters.
• Attempt operations on deleted or stale handles.
• Simulate unexpected API responses if possible or find edge cases where projection might fail.

Surface Areas to Cover

1. Root & Initialization (Stitch)

• Zero Config: Verify the singleton works without explicit config if STITCH_API_KEY is present.
• Invalid Config: Pass an empty API key or invalid base URL to StitchToolClient and verify that the first call fails with a clear authentication or connection error, not a generic noise error.

2. Project Lifecycle (Project)

• Handle Creation: Verify that stitch.project('invalid-id') does not throw (lazy instantiation) but the first call on it fails safely.
• Factory vs API: Verify that creating a project handle via the factory doesn't trigger API calls, but methods like project.listScreens() do.

3. Screen Lifecycle (Screen)

• The Handover: Verify that properties from Project.generate() are correctly populated on the returned Screen instances without a second fetch.
• Null Safety in Projections: Test tools or scenarios that return empty arrays or missing optional fields. Verify that the SDK handle handles them as undefined or empty arrays rather than crashing on null property access!

4. Design System (DesignSystem)

• Application: Create a design system, and apply it to a list of screens. Verify that if the list is empty or invalid, the SDK fails cleanly!
• Handles: Verify that project.designSystem('ds-id') correctly receives the projectId and injects it into calls like ds.apply(...).

Tricky Situations Matrix (Standard Functional Edges)

| Scenario | What to try | Expected Behavior |

| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |

| Stale Handles | Create a screen, delete the project, then try to edit the screen handle. | Clean API error indicating resource not found, wrapped in StitchError. |

| Empty Prompts | Call project.generate('') or with only whitespace. | Safe rejection or clear API error, no crash in codegen. |

| Projections on null | Force an API call that returns a response without the expected projection field (if you can simulate or find such a tool fallback case). | The SDK should use optional chaining (e.g., raw?.prop) and return undefined rather than throwing TypeError: cannot read property of undefined. |

| Massive arrays | Pass hundreds of screen IDs to ds.apply(). | Check if it hits payload limits gracefully or fails with a clear message. |

Diagnostic Hygiene

• Always wrap your test calls in try/catch.
• Log the error and inspect error.code or error.name to see if it's a StitchError or a generic raw error.
• If an execution throws a raw TypeError or "cannot read property of undefined", that is a HIGH PRIORITY BUG in the SDK's projection logic!

Test Template: The Full Workflow Bash

Use this template to run a quick end-to-end bash session.

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();