@su-record/vibe 2.5.11 → 2.5.13

package/package.json

@@ -1,83 +1,83 @@
-{
-  "name": "@su-record/vibe",
-  "version": "2.5.11",
-  "description": "Vibe - Claude Code exclusive SPEC-driven AI coding framework with 35+ integrated tools",
-  "type": "module",
-  "main": "dist/cli/index.js",
-  "exports": {
-    ".": "./dist/cli/index.js",
-    "./tools": "./dist/tools/index.js",
-    "./tools/memory": "./dist/tools/memory/index.js",
-    "./tools/convention": "./dist/tools/convention/index.js",
-    "./tools/semantic": "./dist/tools/semantic/index.js",
-    "./tools/ui": "./dist/tools/ui/index.js",
-    "./tools/time": "./dist/tools/time/index.js",
-    "./orchestrator": "./dist/orchestrator/index.js",
-    "./lib/gpt": "./dist/lib/gpt-api.js",
-    "./lib/gemini": "./dist/lib/gemini-api.js"
-  },
-  "bin": {
-    "vibe": "./dist/cli/index.js"
-  },
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "prepublishOnly": "npm run build",
-    "postinstall": "node dist/cli/postinstall.js"
-  },
-  "keywords": [
-    "ai",
-    "vibe",
-    "coding",
-    "spec-driven",
-    "claude",
-    "mcp",
-    "framework",
-    "requirements",
-    "user-story",
-    "ultrawork",
-    "parallel-agents",
-    "memory-management",
-    "knowledge-graph",
-    "code-analysis",
-    "code-quality"
-  ],
-  "author": "Su",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/su-record/vibe.git"
-  },
-  "homepage": "https://github.com/su-record/vibe#readme",
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.6",
-    "better-sqlite3": "^12.4.1",
-    "chalk": "^5.3.0",
-    "glob": "^11.0.3",
-    "ts-morph": "^26.0.0"
-  },
-  "devDependencies": {
-    "@types/better-sqlite3": "^7.6.13",
-    "@types/glob": "^8.1.0",
-    "@types/node": "^22.0.0",
-    "typescript": "^5.5.4",
-    "vitest": "^4.0.9"
-  },
-  "files": [
-    "dist/",
-    "vibe/",
-    "languages/",
-    "commands/",
-    "agents/",
-    "skills/",
-    "hooks/",
-    "CLAUDE.md",
-    "README.md",
-    "LICENSE"
-  ]
-}
+{
+  "name": "@su-record/vibe",
+  "version": "2.5.13",
+  "description": "Vibe - Claude Code exclusive SPEC-driven AI coding framework with 35+ integrated tools",
+  "type": "module",
+  "main": "dist/cli/index.js",
+  "exports": {
+    ".": "./dist/cli/index.js",
+    "./tools": "./dist/tools/index.js",
+    "./tools/memory": "./dist/tools/memory/index.js",
+    "./tools/convention": "./dist/tools/convention/index.js",
+    "./tools/semantic": "./dist/tools/semantic/index.js",
+    "./tools/ui": "./dist/tools/ui/index.js",
+    "./tools/time": "./dist/tools/time/index.js",
+    "./orchestrator": "./dist/orchestrator/index.js",
+    "./lib/gpt": "./dist/lib/gpt-api.js",
+    "./lib/gemini": "./dist/lib/gemini-api.js"
+  },
+  "bin": {
+    "vibe": "./dist/cli/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build",
+    "postinstall": "node dist/cli/postinstall.js"
+  },
+  "keywords": [
+    "ai",
+    "vibe",
+    "coding",
+    "spec-driven",
+    "claude",
+    "mcp",
+    "framework",
+    "requirements",
+    "user-story",
+    "ultrawork",
+    "parallel-agents",
+    "memory-management",
+    "knowledge-graph",
+    "code-analysis",
+    "code-quality"
+  ],
+  "author": "Su",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/su-record/vibe.git"
+  },
+  "homepage": "https://github.com/su-record/vibe#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.6",
+    "better-sqlite3": "^12.4.1",
+    "chalk": "^5.3.0",
+    "glob": "^11.0.3",
+    "ts-morph": "^26.0.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/glob": "^8.1.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.4",
+    "vitest": "^4.0.9"
+  },
+  "files": [
+    "dist/",
+    "vibe/",
+    "languages/",
+    "commands/",
+    "agents/",
+    "skills/",
+    "hooks/",
+    "CLAUDE.md",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/skills/brand-assets.md

@@ -0,0 +1,141 @@
+---
+name: brand-assets
+description: "Auto-generate app icons and favicons from SPEC brand information using Gemini Image API"
+triggers: [icon, favicon, brand, logo, app icon, branding, assets]
+priority: 65
+---
+# Brand Assets Generation Skill
+
+Auto-generate app icons and favicons based on SPEC brand information.
+
+## When to Use
+
+- First-time project setup with `/vibe.run`
+- When SPEC contains brand/design information
+- When Gemini API key is configured
+
+## Prerequisites
+
+- Gemini API key configured (`vibe gemini auth`)
+- SPEC with brand context (app name, colors, style)
+
+## Generated Assets
+
+### Web
+- `favicon.ico` (16x16, 32x32, 48x48)
+- `favicon-16x16.png`
+- `favicon-32x32.png`
+- `apple-touch-icon.png` (180x180)
+- `android-chrome-192x192.png`
+- `android-chrome-512x512.png`
+
+### Mobile (if applicable)
+- iOS: `AppIcon.appiconset/` with all sizes
+- Android: `mipmap-*/` adaptive icons
+
+## SPEC Brand Section
+
+For best results, include brand info in your SPEC:
+
+```yaml
+<context>
+Brand:
+  - App Name: MyApp
+  - Primary Color: #2F6BFF
+  - Style: Modern, minimal, flat design
+  - Icon Concept: Abstract geometric shape representing connectivity
+</context>
+```
+
+## Generation Flow
+
+```
+SPEC Brand Info
+      |
+      v
+Extract: name, colors, style keywords
+      |
+      v
+Generate Prompt: "App icon for [name], [style], [colors]..."
+      |
+      v
+Gemini Image API (imagen-3)
+      |
+      v
+Resize & Convert: All platform sizes
+      |
+      v
+Save to: public/ or assets/
+```
+
+## Auto-Trigger Conditions
+
+1. First `/vibe.run` execution (no existing icons)
+2. SPEC contains brand/design context
+3. Gemini API key is available
+4. `--generate-icons` flag passed
+
+## Skip Conditions
+
+- Icons already exist (unless `--regenerate-icons`)
+- No brand info in SPEC
+- Gemini API not configured
+
+## Prompt Template
+
+```
+Create a modern app icon for "[APP_NAME]".
+
+Style: [STYLE_KEYWORDS]
+Primary color: [PRIMARY_COLOR]
+Design: Minimalist, professional, suitable for mobile app
+Format: Square, clean edges, simple recognizable shape
+Background: Solid color or subtle gradient
+
+Requirements:
+- Works at small sizes (16x16 to 512x512)
+- No text or letters
+- Single focal element
+- High contrast for visibility
+```
+
+## Manual Usage
+
+```bash
+# Generate via hook script (when Gemini configured)
+node hooks/scripts/generate-brand-assets.js \
+  --name "MyApp" \
+  --color "#2F6BFF" \
+  --style "modern minimal" \
+  --output "./public"
+```
+
+## Integration with /vibe.run
+
+During Phase 1 (Setup), if brand assets don't exist:
+
+1. Parse SPEC for brand context
+2. Generate icon via Gemini Image API
+3. Create all size variants
+4. Place in appropriate directories
+5. Update manifest files if needed
+
+## Fallback Strategy
+
+If Gemini Image fails:
+1. Generate text-based monogram icon (first letter)
+2. Use project primary color as background
+3. Create simple geometric placeholder
+
+## Output Structure
+
+```
+public/
+  favicon.ico
+  favicon-16x16.png
+  favicon-32x32.png
+  apple-touch-icon.png
+  android-chrome-192x192.png
+  android-chrome-512x512.png
+  site.webmanifest
+```

package/skills/commerce-patterns.md

@@ -0,0 +1,361 @@
+---
+name: commerce-patterns
+description: "E-commerce domain patterns - cart, payment, inventory with transaction safety"
+triggers: [commerce, ecommerce, cart, payment, checkout, inventory, stock, order, pg, toss, stripe]
+priority: 70
+---
+# Commerce Patterns Skill
+
+E-commerce domain patterns for reliable transactions.
+
+## When to Use
+
+- Shopping cart implementation
+- Payment integration (PG, Stripe, Toss)
+- Inventory/stock management
+- Order processing systems
+
+## Core Patterns
+
+### 1. Cart (Shopping Cart)
+
+#### State Model
+```typescript
+interface CartItem {
+  productId: string;
+  variantId?: string;
+  quantity: number;
+  price: number;           // Snapshot at add time
+  originalPrice: number;   // For comparison
+  addedAt: Date;
+}
+
+interface Cart {
+  id: string;
+  userId?: string;         // null for guest
+  sessionId: string;       // For guest merge
+  items: CartItem[];
+  couponCode?: string;
+  updatedAt: Date;
+  expiresAt: Date;         // Cart expiration
+}
+```
+
+#### Key Patterns
+
+| Pattern | Description |
+|---------|-------------|
+| **Guest → User Merge** | Merge localStorage cart on login |
+| **Price Snapshot** | Store price at add time, revalidate at checkout |
+| **Expiration** | Clear abandoned carts after N days |
+| **Validation** | Check stock/price at checkout entry |
+
+#### Implementation
+```typescript
+class CartService {
+  async addItem(cartId: string, item: AddItemRequest): Promise<Cart> {
+    // 1. Validate product exists and in stock
+    const product = await this.productService.get(item.productId);
+    if (!product || product.stock < item.quantity) {
+      throw new OutOfStockError();
+    }
+
+    // 2. Snapshot current price
+    const cartItem: CartItem = {
+      ...item,
+      price: product.currentPrice,
+      originalPrice: product.originalPrice,
+      addedAt: new Date(),
+    };
+
+    // 3. Add or update quantity
+    return this.cartRepository.upsertItem(cartId, cartItem);
+  }
+
+  async mergeGuestCart(userId: string, sessionId: string): Promise<Cart> {
+    const guestCart = await this.cartRepository.findBySession(sessionId);
+    const userCart = await this.cartRepository.findByUser(userId);
+
+    if (!guestCart) return userCart;
+
+    // Merge: user cart takes priority for duplicates
+    const merged = this.mergeItems(userCart.items, guestCart.items);
+    await this.cartRepository.delete(guestCart.id);
+
+    return this.cartRepository.update(userCart.id, { items: merged });
+  }
+}
+```
+
+### 2. Payment
+
+#### State Machine
+```
+PENDING → PROCESSING → AUTHORIZED → CAPTURED → COMPLETED
+                    ↘ FAILED
+                    ↘ CANCELED
+COMPLETED → REFUND_REQUESTED → REFUNDED (partial/full)
+```
+
+#### Idempotency Pattern (Critical)
+```typescript
+interface PaymentRequest {
+  orderId: string;
+  amount: number;
+  currency: string;
+  idempotencyKey: string;  // REQUIRED: `order_${orderId}_${timestamp}`
+  paymentMethod: PaymentMethod;
+}
+
+class PaymentService {
+  async processPayment(request: PaymentRequest): Promise<PaymentResult> {
+    // 1. Check idempotency - prevent duplicate charges
+    const existing = await this.paymentRepository.findByIdempotencyKey(
+      request.idempotencyKey
+    );
+    if (existing) {
+      return existing.result;  // Return cached result
+    }
+
+    // 2. Create payment record (PENDING)
+    const payment = await this.paymentRepository.create({
+      ...request,
+      status: 'PENDING',
+    });
+
+    try {
+      // 3. Call PG adapter
+      const pgResult = await this.pgAdapter.authorize(request);
+
+      // 4. Update status
+      return this.paymentRepository.update(payment.id, {
+        status: pgResult.success ? 'AUTHORIZED' : 'FAILED',
+        pgTransactionId: pgResult.transactionId,
+        result: pgResult,
+      });
+    } catch (error) {
+      await this.paymentRepository.update(payment.id, {
+        status: 'FAILED',
+        error: error.message,
+      });
+      throw error;
+    }
+  }
+}
+```
+
+#### PG Adapter Pattern
+```typescript
+interface PGAdapter {
+  authorize(request: PaymentRequest): Promise<PGResult>;
+  capture(transactionId: string): Promise<PGResult>;
+  cancel(transactionId: string): Promise<PGResult>;
+  refund(transactionId: string, amount?: number): Promise<PGResult>;
+}
+
+// Implementations
+class TossPaymentsAdapter implements PGAdapter { /* ... */ }
+class StripeAdapter implements PGAdapter { /* ... */ }
+class PortOneAdapter implements PGAdapter { /* ... */ }
+```
+
+#### Webhook Handling
+```typescript
+class PaymentWebhookHandler {
+  async handle(event: WebhookEvent): Promise<void> {
+    // 1. Verify signature
+    if (!this.verifySignature(event)) {
+      throw new UnauthorizedError();
+    }
+
+    // 2. Idempotency check - process each event only once
+    const processed = await this.eventStore.find(event.id);
+    if (processed) {
+      return;  // Already processed
+    }
+
+    // 3. Process event
+    await this.processEvent(event);
+
+    // 4. Mark as processed
+    await this.eventStore.save({
+      eventId: event.id,
+      processedAt: new Date(),
+    });
+  }
+}
+```
+
+### 3. Inventory (Stock Management)
+
+#### Reservation Pattern (Two-Phase)
+```typescript
+interface StockReservation {
+  id: string;
+  productId: string;
+  quantity: number;
+  orderId: string;
+  status: 'RESERVED' | 'COMMITTED' | 'RELEASED';
+  expiresAt: Date;         // Auto-release if not committed
+  createdAt: Date;
+}
+
+class InventoryService {
+  // Phase 1: Reserve stock (at checkout start)
+  async reserve(orderId: string, items: OrderItem[]): Promise<void> {
+    for (const item of items) {
+      // Atomic decrement with check
+      const result = await this.db.query(`
+        UPDATE products
+        SET reserved_stock = reserved_stock + $1
+        WHERE id = $2
+          AND (available_stock - reserved_stock) >= $1
+        RETURNING *
+      `, [item.quantity, item.productId]);
+
+      if (result.rowCount === 0) {
+        // Rollback previous reservations
+        await this.releaseAll(orderId);
+        throw new InsufficientStockError(item.productId);
+      }
+
+      await this.reservationRepository.create({
+        orderId,
+        productId: item.productId,
+        quantity: item.quantity,
+        status: 'RESERVED',
+        expiresAt: addMinutes(new Date(), 15),  // 15min hold
+      });
+    }
+  }
+
+  // Phase 2: Commit stock (after payment success)
+  async commit(orderId: string): Promise<void> {
+    const reservations = await this.reservationRepository.findByOrder(orderId);
+
+    for (const reservation of reservations) {
+      await this.db.query(`
+        UPDATE products
+        SET
+          available_stock = available_stock - $1,
+          reserved_stock = reserved_stock - $1
+        WHERE id = $2
+      `, [reservation.quantity, reservation.productId]);
+
+      await this.reservationRepository.update(reservation.id, {
+        status: 'COMMITTED',
+      });
+    }
+  }
+
+  // Rollback: Release stock (payment failed or timeout)
+  async release(orderId: string): Promise<void> {
+    const reservations = await this.reservationRepository.findByOrder(orderId);
+
+    for (const reservation of reservations) {
+      if (reservation.status === 'RESERVED') {
+        await this.db.query(`
+          UPDATE products
+          SET reserved_stock = reserved_stock - $1
+          WHERE id = $2
+        `, [reservation.quantity, reservation.productId]);
+
+        await this.reservationRepository.update(reservation.id, {
+          status: 'RELEASED',
+        });
+      }
+    }
+  }
+}
+```
+
+#### Concurrency Control
+```typescript
+// Option 1: Optimistic Locking
+await db.query(`
+  UPDATE products
+  SET stock = stock - $1, version = version + 1
+  WHERE id = $2 AND version = $3 AND stock >= $1
+`, [quantity, productId, expectedVersion]);
+
+// Option 2: Pessimistic Locking (for high contention)
+await db.query(`
+  SELECT * FROM products WHERE id = $1 FOR UPDATE
+`, [productId]);
+
+// Option 3: Redis Distributed Lock
+const lock = await redlock.lock(`stock:${productId}`, 5000);
+try {
+  // Update stock
+} finally {
+  await lock.unlock();
+}
+```
+
+## Order Flow (Complete)
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  CHECKOUT FLOW                                              │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  1. Cart Validation                                         │
+│     └─ Revalidate prices, check stock availability          │
+│                                                             │
+│  2. Order Creation (PENDING)                                │
+│     └─ Generate orderId, snapshot cart                      │
+│                                                             │
+│  3. Stock Reservation                                       │
+│     └─ Reserve inventory (15min hold)                       │
+│                                                             │
+│  4. Payment Processing                                      │
+│     ├─ Success → Order PAID, Stock COMMIT                   │
+│     └─ Failure → Order FAILED, Stock RELEASE                │
+│                                                             │
+│  5. Order Confirmation                                      │
+│     └─ Send notification, trigger fulfillment               │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Common Bugs & Prevention
+
+| Bug | Cause | Prevention |
+|-----|-------|------------|
+| **Duplicate payment** | User double-click, webhook retry | Idempotency key |
+| **Negative stock** | Race condition | Atomic update with check |
+| **Price mismatch** | Price changed during checkout | Snapshot + revalidation |
+| **Orphan reservation** | Payment timeout without release | TTL + scheduled cleanup |
+| **Lost webhook** | Network failure | Retry + idempotent handler |
+| **Order state corruption** | Concurrent updates | State machine + versioning |
+
+## Integration with /vibe.run
+
+During commerce feature implementation:
+
+1. **Phase 1**: Define domain models (Cart, Order, Payment, Inventory)
+2. **Phase 2**: Implement core services with patterns above
+3. **Phase 3**: Add PG adapter and webhook handlers
+4. **Phase 4**: Implement compensating transactions (Saga)
+5. **Phase 5**: E2E test critical flows
+
+## Checklist
+
+### Cart
+- [ ] Guest/user cart merge on login
+- [ ] Price snapshot at add time
+- [ ] Stock validation at checkout
+- [ ] Cart expiration cleanup
+
+### Payment
+- [ ] Idempotency key on all requests
+- [ ] Webhook signature verification
+- [ ] Duplicate event handling
+- [ ] Timeout/retry strategy
+- [ ] Refund flow tested
+
+### Inventory
+- [ ] Two-phase reservation (reserve → commit/release)
+- [ ] Atomic stock updates
+- [ ] Reservation TTL and cleanup job
+- [ ] Concurrency control tested