@hienlh/ppm 0.9.80 → 0.9.81

package/.opencode/skills/stitch/references/design-to-code-pipeline.md

@@ -0,0 +1,128 @@
+# Design-to-Code Pipeline Patterns
+
+Orchestration workflows chaining Stitch design generation with ClaudeKit implementation skills.
+
+## Basic Pipeline
+
+```
+Prompt -> Stitch Generate -> Export HTML -> Claude Implements Components
+```
+
+### Steps
+
+1. User describes desired UI in natural language
+2. Run `stitch-generate.ts` with the prompt
+3. Show preview image to user for approval
+4. Run `stitch-export.ts --format all` to get HTML + DESIGN.md
+5. Hand DESIGN.md to implementation skill
+6. Implementation skill reads DESIGN.md and codes components
+
+### Example
+
+```bash
+# 1. Generate
+npx tsx stitch-generate.ts "E-commerce product page with image gallery, price, reviews, add-to-cart button"
+
+# 2. Export
+npx tsx stitch-export.ts <screen-id> --format all --output ./stitch-exports/
+
+# 3. Implementation skill reads ./stitch-exports/DESIGN.md
+# 4. Activate ck:frontend-design to implement React components from the spec
+```
+
+## Advanced Pipeline (with Variants)
+
+```
+Prompt -> Generate -> Variants -> User Picks -> Export -> Implement
+```
+
+### Steps
+
+1. Generate base design
+2. Generate 2-3 variants with different aspects (color, layout)
+3. Show all variants to user
+4. User selects preferred variant
+5. Export selected variant
+6. Hand off to implementation
+
+### Example
+
+```bash
+# Generate with variants
+npx tsx stitch-generate.ts "SaaS pricing page" --variants 3
+
+# User reviews images, picks variant 2
+npx tsx stitch-export.ts <variant-2-screen-id> --format all
+```
+
+## DESIGN.md Specification
+
+DESIGN.md is an agent-readable markdown file containing extracted design tokens.
+
+### Structure
+
+```markdown
+# Design System
+
+## Colors
+- `bg-blue-600` (primary background)
+- `text-gray-900` (body text)
+- `border-gray-200` (dividers)
+
+## Typography
+- `text-2xl font-bold` (headings)
+- `text-base font-normal` (body)
+
+## Spacing
+- `p-4` (card padding)
+- `gap-6` (grid gaps)
+
+## Components
+- `<nav>` (top navigation)
+- `<section>` (content sections)
+- `<form>` (user inputs)
+- `<button>` (actions)
+
+## Notes
+- Generated by Google Stitch AI
+- Tailwind CSS utility classes
+```
+
+### How Implementation Skills Consume It
+
+1. Skill checks for `DESIGN.md` in project root or plan directory
+2. If found: reads tokens and uses them as constraints for implementation
+3. If not found: falls back to text-based design (existing behavior)
+4. DESIGN.md takes precedence over verbal design descriptions
+
+## Skill Routing
+
+| Design Need | Skill | What It Does |
+|-------------|-------|-------------|
+| React/Vue/Svelte components | `ck:frontend-design` | Converts Tailwind HTML to framework components |
+| Full page with style guide | `ck:ui-ux-pro-max` | Builds complete layouts with design system |
+| Design token extraction | `ck:ui-styling` | Extracts shadcn/Tailwind tokens from DESIGN.md |
+
+## Handoff Protocol
+
+1. `ck:stitch` exports artifacts to `./stitch-exports/` (or plan directory)
+2. Copy `DESIGN.md` to project root if implementation skill expects it there
+3. Activate target skill with instruction: "Implement from DESIGN.md in project root"
+4. Target skill reads DESIGN.md, applies tokens, generates code
+5. No modifications needed to existing skills — they read DESIGN.md opportunistically
+
+## Quota-Aware Pipeline
+
+Always check quota before generating:
+
+```bash
+# Pre-check
+npx tsx stitch-quota.ts check
+
+# If exhausted (exit code 2):
+# -> Skip Stitch, use ck:ui-ux-pro-max for text-based design instead
+
+# If available:
+npx tsx stitch-generate.ts "<prompt>"
+npx tsx stitch-quota.ts increment
+```

package/.opencode/skills/stitch/references/quota-management.md

@@ -0,0 +1,64 @@
+# Quota Management
+
+Google Stitch free tier quota tracking and conservation strategies.
+
+## Limits
+
+| Pool | Credits/Day | Reset |
+|------|-------------|-------|
+| Daily Credits (generate, variants) | 400 | Midnight UTC |
+| Redesign Credits (edit_screens) | 15 | Midnight UTC |
+
+Each generation = 1 credit. Each variant = 1 credit. Each edit = 1 redesign credit (separate pool).
+
+## Local Tracking
+
+Stitch SDK has no programmatic quota check endpoint. ClaudeKit tracks locally:
+
+**File:** `~/.claudekit/.stitch-quota.json`
+
+```json
+{
+  "date": "2026-03-23",
+  "count": 42,
+  "limit": 400
+}
+```
+
+**Auto-reset:** When `date` != today (UTC), count resets to 0.
+
+**Override limit:** `export STITCH_QUOTA_LIMIT="300"` (if Google increases limits).
+
+## Warning Thresholds
+
+| Remaining | Action |
+|-----------|--------|
+| > 20% | Normal operation |
+| < 20% | `[!] Low quota` warning printed |
+| 0 | `[X] Exhausted` — exit code 2, suggest fallback |
+
+## Conservation Tips
+
+1. **Use variants instead of regenerating** — 3 variants = 3 credits vs regenerating 3 times = 3 credits, but variants are more purposeful
+2. **Use `screen.edit()` to refine** — Editing costs 1 credit but preserves context
+3. **Export early** — Don't regenerate just to see the design again; export HTML/image once
+4. **Batch planning** — Plan all designs for the day, generate in one session
+5. **Review prompts** — Better prompts = fewer regenerations
+
+## Fallback Workflow
+
+When quota is exhausted:
+
+1. `stitch-quota.ts check` returns exit code 2
+2. Skill prints: "Daily quota exhausted. Use ck:ui-ux-pro-max as fallback."
+3. Activate `ck:ui-ux-pro-max` with the same design prompt
+4. `ui-ux-pro-max` generates text-based design spec (no external API needed)
+5. Proceed with implementation using text-based spec
+
+## Drift Warning
+
+Local tracking can drift if user generates designs outside ClaudeKit (via Stitch web UI or other tools). If you hit `RATE_LIMITED` error despite local tracker showing credits available:
+
+1. Run `npx tsx stitch-quota.ts reset`
+2. Set count to match actual usage (or leave at 0 if unknown)
+3. Stitch API itself enforces the real limit — local tracker is advisory only

package/.opencode/skills/stitch/references/stitch-mcp-setup.md

@@ -0,0 +1,95 @@
+# Stitch MCP Server Setup
+
+Three options for connecting Google Stitch as an MCP server with Claude Code.
+
+## Option A: API Key (Recommended for Most Users)
+
+Simplest setup. No Google Cloud dependency.
+
+### 1. Get API Key
+
+1. Sign in at https://stitch.withgoogle.com
+2. Go to Settings -> API Keys
+3. Click "Generate New Key"
+4. Copy `sk_...` key
+
+### 2. Add to `.opencode/.mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "stitch": {
+      "command": "npx",
+      "args": ["@_davideast/stitch-mcp", "proxy"],
+      "env": {
+        "STITCH_API_KEY": "sk_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### 3. Verify
+
+Restart Claude Code. You should see Stitch tools available:
+- `create_project` — Create new design project
+- `generate_screen` — Generate UI from prompt
+- `export_html` — Export as HTML/Tailwind
+- `export_image` — Export screenshot
+
+## Option B: Google Cloud (For GCP Users)
+
+Uses gcloud credentials. Zero API key management.
+
+### 1. Setup gcloud
+
+```bash
+gcloud auth login
+gcloud config set project YOUR_PROJECT_ID
+gcloud beta services mcp enable stitch.googleapis.com
+```
+
+### 2. Add to `.opencode/.mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "stitch": {
+      "command": "npx",
+      "args": ["-y", "stitch-mcp"],
+      "env": {
+        "GOOGLE_CLOUD_PROJECT": "your-gcp-project-id"
+      }
+    }
+  }
+}
+```
+
+## Option C: Auto-Installer (Interactive)
+
+Guided wizard, auto-detects environment.
+
+```bash
+npx stitch-mcp-auto
+# Opens browser at http://localhost:8086
+# Follow wizard to configure
+```
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| "AUTH_FAILED" on startup | Verify API key or re-run `gcloud auth login` |
+| Tools not appearing | Restart Claude Code after config change |
+| Timeout on generation | Stitch is processing; wait 10-30s for complex designs |
+| "RATE_LIMITED" errors | Daily quota exceeded; wait until midnight UTC |
+
+## MCP Config Location
+
+| OS | Path |
+|----|------|
+| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Windows | `%AppData%\Claude\claude_desktop_config.json` |
+| Linux | `~/.config/Claude/claude_desktop_config.json` |
+
+For Claude Code CLI: use `.opencode/.mcp.json` in project root (preferred for ClaudeKit).

package/.opencode/skills/stitch/references/stitch-sdk-api.md

@@ -0,0 +1,136 @@
+# Stitch SDK API Reference
+
+Condensed reference for `@google/stitch-sdk`. Agent-optimized — covers common operations only.
+
+## Installation
+
+```bash
+npm install @google/stitch-sdk
+# Optional: Vercel AI SDK integration
+npm install @google/stitch-sdk ai
+```
+
+## Authentication
+
+```bash
+export STITCH_API_KEY="sk_..."  # From https://stitch.withgoogle.com/settings/api
+```
+
+SDK auto-reads `STITCH_API_KEY` from environment. No explicit config needed.
+
+## Core API
+
+### Stitch (root singleton)
+
+```typescript
+import { stitch } from "@google/stitch-sdk";
+
+const projects = await stitch.projects();         // List all projects
+const project = stitch.project("my-id");          // Get project handle (sync)
+```
+
+### Project
+
+```typescript
+const project = stitch.project("project-123");  // sync — returns handle
+
+// Generate screen from prompt (positional params, uppercase device types)
+const screen = await project.generate(
+  "Login page with email/password",
+  "MOBILE"  // optional: "MOBILE" | "DESKTOP" | "TABLET" | "AGNOSTIC"
+);
+
+const screens = await project.screens();           // List all screens
+const screen = await project.getScreen(screenId);  // Get specific screen
+```
+
+### Screen
+
+```typescript
+// Export
+const htmlUrl = await screen.getHtml();     // Returns download URL (HTML + Tailwind)
+const imageUrl = await screen.getImage();   // Returns download URL (PNG screenshot)
+
+// Edit/refine (positional: prompt, deviceType?, modelId?)
+const edited = await screen.edit("Make colors darker, add search bar");
+
+// Generate variants (positional: prompt, variantOptions, deviceType?, modelId?)
+const variants = await screen.variants("Different color schemes", {
+  variantCount: 3,            // 1-5 variants
+  creativeRange: "medium",    // "low" | "medium" | "high"
+  aspects: ["COLOR_SCHEME"]   // "COLOR_SCHEME" | "LAYOUT" | etc.
+});
+```
+
+### StitchToolClient (low-level MCP access)
+
+```typescript
+import { StitchToolClient } from "@google/stitch-sdk";
+
+const client = new StitchToolClient({ apiKey: "sk_..." });
+const tools = await client.listTools();
+const result = await client.callTool("create_project", { title: "My App" });
+```
+
+### Vercel AI SDK Integration
+
+```typescript
+import { stitchTools } from "@google/stitch-sdk/ai";
+import { generateText } from "ai";
+
+const { text } = await generateText({
+  model: yourModel,
+  tools: stitchTools(),
+  prompt: "Create a modern dashboard"
+});
+```
+
+## Type Definitions
+
+```typescript
+type DeviceType = "DEVICE_TYPE_UNSPECIFIED" | "MOBILE" | "DESKTOP" | "TABLET" | "AGNOSTIC";
+type ModelId = "MODEL_ID_UNSPECIFIED" | "GEMINI_3_PRO" | "GEMINI_3_FLASH";
+
+interface Stitch {
+  projects(): Promise<Project[]>;
+  createProject(title?: string): Promise<Project>;
+  project(id: string): Project;  // sync — returns handle, no API call
+}
+
+interface Project {
+  id: string;
+  generate(prompt: string, deviceType?: DeviceType, modelId?: ModelId): Promise<Screen>;
+  screens(): Promise<Screen[]>;
+  getScreen(screenId: string): Promise<Screen>;
+}
+
+interface Screen {
+  id: string;
+  getHtml(): Promise<string>;   // Download URL
+  getImage(): Promise<string>;  // Download URL
+  edit(prompt: string, deviceType?: DeviceType, modelId?: ModelId): Promise<Screen>;
+  variants(prompt: string, variantOptions: any, deviceType?: DeviceType, modelId?: ModelId): Promise<Screen[]>;
+}
+
+class StitchError extends Error {
+  code: "AUTH_FAILED" | "NOT_FOUND" | "RATE_LIMITED" | string;
+}
+```
+
+## Error Handling
+
+| Code | Meaning | Action |
+|------|---------|--------|
+| `AUTH_FAILED` | Bad/missing API key | Check `STITCH_API_KEY` env var |
+| `NOT_FOUND` | Screen/project doesn't exist | Verify ID |
+| `RATE_LIMITED` | Daily quota exceeded | Wait until midnight UTC or use fallback |
+
+```typescript
+try {
+  const screen = await project.generate(prompt);
+} catch (error) {
+  if (error.code === "RATE_LIMITED") {
+    console.error("Quota exceeded — use ck:ui-ux-pro-max fallback");
+  }
+}
+```

package/.opencode/skills/stitch/scripts/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "stitch-scripts",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "ClaudeKit Stitch skill SDK wrapper scripts",
+  "scripts": {
+    "generate": "tsx stitch-generate.ts",
+    "export": "tsx stitch-export.ts",
+    "quota": "tsx stitch-quota.ts"
+  },
+  "dependencies": {
+    "@google/stitch-sdk": ">=0.0.3 <1.0.0"
+  },
+  "devDependencies": {
+    "tsx": "^4.0.0"
+  }
+}

package/.opencode/skills/stitch/scripts/stitch-export.ts

@@ -0,0 +1,173 @@
+/**
+ * stitch-export.ts — Export Stitch designs as HTML, image, or DESIGN.md.
+ *
+ * Usage:
+ *   npx tsx stitch-export.ts <screen-id> [--project <id>] [--format html|image|all] [--output <dir>]
+ *
+ * Env: STITCH_API_KEY (required), STITCH_PROJECT_ID (optional default)
+ */
+
+import { stitch } from "@google/stitch-sdk";
+import fs from "fs";
+import path from "path";
+
+// -- Argument parsing --
+
+const args = process.argv.slice(2);
+
+function getFlag(name: string): string | undefined {
+  const idx = args.indexOf(`--${name}`);
+  if (idx === -1 || idx + 1 >= args.length) return undefined;
+  return args[idx + 1];
+}
+
+// Extract positional args (skip flags and their values)
+function getPositionalArgs(): string[] {
+  const positional: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i].startsWith("--")) {
+      i++; // skip flag value
+    } else {
+      positional.push(args[i]);
+    }
+  }
+  return positional;
+}
+
+const screenId = getPositionalArgs()[0];
+const projectId =
+  getFlag("project") || process.env.STITCH_PROJECT_ID || "claudekit-default";
+const format = getFlag("format") || "all";
+const outputDir = getFlag("output") || "./stitch-exports";
+
+if (!screenId) {
+  console.error("Usage: npx tsx stitch-export.ts <screen-id> [--project <id>] [--format html|image|all] [--output <dir>]");
+  process.exit(1);
+}
+
+if (!process.env.STITCH_API_KEY) {
+  console.error("[X] STITCH_API_KEY not set. Get one at https://stitch.withgoogle.com/settings/api");
+  process.exit(1);
+}
+
+// -- Helpers --
+
+async function downloadFile(url: string, dest: string): Promise<void> {
+  const response = await fetch(url);
+  if (!response.ok) throw new Error(`Download failed: ${response.status} ${response.statusText}`);
+  const buffer = Buffer.from(await response.arrayBuffer());
+  fs.writeFileSync(dest, buffer);
+}
+
+/**
+ * Generate a DESIGN.md from HTML content by extracting Tailwind classes,
+ * color values, typography patterns, and component structure.
+ */
+function generateDesignMd(html: string): string {
+  const lines: string[] = ["# Design System", "", "Auto-generated from Google Stitch export.", ""];
+
+  // Extract colors from Tailwind classes and inline styles
+  const colorMatches = html.match(/(?:bg|text|border)-(?:\w+)-(\d+)/g) || [];
+  const uniqueColors = [...new Set(colorMatches)].slice(0, 20);
+  if (uniqueColors.length > 0) {
+    lines.push("## Colors", "");
+    uniqueColors.forEach((c) => lines.push(`- \`${c}\``));
+    lines.push("");
+  }
+
+  // Extract typography classes
+  const textMatches = html.match(/(?:text-(?:xs|sm|base|lg|xl|2xl|3xl|4xl|5xl)|font-(?:thin|light|normal|medium|semibold|bold|extrabold))/g) || [];
+  const uniqueText = [...new Set(textMatches)].slice(0, 15);
+  if (uniqueText.length > 0) {
+    lines.push("## Typography", "");
+    uniqueText.forEach((t) => lines.push(`- \`${t}\``));
+    lines.push("");
+  }
+
+  // Extract spacing patterns
+  const spacingMatches = html.match(/(?:p|m|gap|space)-(?:x|y)?-?\d+/g) || [];
+  const uniqueSpacing = [...new Set(spacingMatches)].slice(0, 15);
+  if (uniqueSpacing.length > 0) {
+    lines.push("## Spacing", "");
+    uniqueSpacing.forEach((s) => lines.push(`- \`${s}\``));
+    lines.push("");
+  }
+
+  // Extract component-level structure from HTML tags
+  const componentMatches = html.match(/<(section|nav|header|footer|main|aside|form|button|input|table|dialog)[^>]*>/gi) || [];
+  const uniqueComponents = [...new Set(componentMatches.map((c) => c.match(/<(\w+)/)?.[1] || ""))].filter(Boolean);
+  if (uniqueComponents.length > 0) {
+    lines.push("## Components", "");
+    uniqueComponents.forEach((c) => lines.push(`- \`<${c}>\``));
+    lines.push("");
+  }
+
+  lines.push("## Notes", "", "- Generated by Google Stitch AI", "- Tailwind CSS utility classes used throughout", "- Review and customize colors/typography for brand alignment");
+
+  return lines.join("\n");
+}
+
+// -- Main --
+
+async function main() {
+  try {
+    fs.mkdirSync(outputDir, { recursive: true });
+
+    console.error(`[i] Exporting screen ${screenId} from project ${projectId}`);
+    // Resolve project handle — for default project, find by title first
+    let project;
+    if (projectId === "claudekit-default") {
+      const projects = await stitch.projects();
+      const found = projects.find(p => p.data?.title === "claudekit-default");
+      project = found || stitch.project(projectId);
+    } else {
+      project = stitch.project(projectId);
+    }
+    const screen = await project.getScreen(screenId!);
+
+    const exported: Record<string, string> = {};
+
+    // Export HTML
+    if (format === "html" || format === "all") {
+      const htmlUrl = await screen.getHtml();
+      const htmlPath = path.join(outputDir, "design.html");
+      await downloadFile(htmlUrl, htmlPath);
+      exported.html = htmlPath;
+      console.error(`[OK] HTML exported: ${htmlPath}`);
+
+      // Generate DESIGN.md from HTML
+      if (format === "all") {
+        const htmlContent = fs.readFileSync(htmlPath, "utf-8");
+        const designMd = generateDesignMd(htmlContent);
+        const designPath = path.join(outputDir, "DESIGN.md");
+        fs.writeFileSync(designPath, designMd);
+        exported.designMd = designPath;
+        console.error(`[OK] DESIGN.md generated: ${designPath}`);
+      }
+    }
+
+    // Export image
+    if (format === "image" || format === "all") {
+      const imageUrl = await screen.getImage();
+      const imagePath = path.join(outputDir, "design.png");
+      await downloadFile(imageUrl, imagePath);
+      exported.image = imagePath;
+      console.error(`[OK] Image exported: ${imagePath}`);
+    }
+
+    // Output result JSON to stdout
+    console.log(JSON.stringify({ screenId, projectId, format, exported }, null, 2));
+  } catch (error: unknown) {
+    const err = error as { code?: string; message?: string };
+    if (err.code === "NOT_FOUND") {
+      console.error(`[X] Screen "${screenId}" not found in project "${projectId}".`);
+    } else if (err.code === "AUTH_FAILED") {
+      console.error("[X] Authentication failed. Check STITCH_API_KEY env var.");
+    } else {
+      console.error(`[X] Export error: ${err.message || error}`);
+    }
+    process.exit(1);
+  }
+}
+
+main();