google-labs-code/stitch-sdk / .agents/skills/stitch-sdk-bug-bash
stitch-sdk-bug-bash
VerifiedFind bugs in the Stitch SDK using a real API key. Covers standard functional edges and tricky situations.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.2 KB |
SKILL.md
View on GitHub---
name: stitch-sdk-bug-bash
description: Find bugs in the Stitch SDK using a real API key. Covers standard functional edges and tricky situations.
---
# 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.
```typescript
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();
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |