Codebase Audit: Leveraging Existing Assets for Protocol-First Implementation

Executive Summary

This audit identifies existing assets in the Smart Commerce Agent codebase that can be leveraged for the protocol-first implementation, and gaps that need to be filled.

Phase-by-Phase Audit

Phase 0: Product Demo Slice

Component	Existing Code	Location	Status	Gap/Action
Store Catalog	❌	-	NEW	Create `app/(store)/store/page.tsx`
ProductGrid	✅	`app/dashboard/components/genui/product-card.tsx`	READY	Reuse `ProductGrid`, `ProductCard`
ProductCard	✅	`app/dashboard/components/genui/product-card.tsx`	READY	Already has quantity selector, add to cart
SearchBar	❌	-	NEW	Create using shadcn Input + agent integration
FilterSidebar	❌	-	NEW	Create using shadcn Checkbox, Slider
Cart Drawer	❌	-	NEW	Create using shadcn Drawer
Checkout Wizard	❌	-	NEW	Create wizard with shadcn Steps
Orders Page	⚠️	`app/dashboard/components/genui/order-card.tsx`	PARTIAL	Extend for `/orders` route
CopilotKit	❌	-	NEW	Integrate CopilotKit sidebar

Phase 1: shadcn Storefront + GenUI Contract

Component	Existing Code	Location	Status	Gap/Action
GenUI Registry	❌	-	NEW	Create `lib/genui/registry.ts`
GenUI Adapter	❌	-	NEW	Create `lib/genui/adapter.ts`
ProductGrid Component	✅	`app/dashboard/components/genui/product-card.tsx:489`	READY	Reuse existing
ProductCard Component	✅	`app/dashboard/components/genui/product-card.tsx:289`	READY	Full-featured with stock, rating, specs
CartDrawer Component	❌	-	NEW	Build on shadcn Drawer
CheckoutWizard	❌	-	NEW	Build on shadcn Steps
OrderConfirmation	⚠️	`app/dashboard/components/genui/order-card.tsx`	PARTIAL	Extract confirmation view
OrderTracking	⚠️	`app/dashboard/components/genui/order-card.tsx`	PARTIAL	Add tracking events
OrderHistoryGrid	⚠️	`app/dashboard/components/genui/order-card.tsx`	PARTIAL	Create list view

Phase 2: MCP-First Commerce Tool Suite

Cart Tools

Tool	Existing Code	Location	Status	Gap/Action
`cart.get`	✅	`lib/mcp/tools.ts:383-414`	READY	Returns `CartToolResult`
`cart.add_item`	✅	`lib/mcp/tools.ts:416-461`	READY	Basic implementation
`cart.update_quantity`	❌	-	NEW	Add to tools
`cart.remove_item`	❌	-	NEW	Add to tools
`cart.apply_coupon`	❌	-	NEW	Add to tools
`cart.clear`	❌	-	NEW	Add to tools

Existing Cart Code (lib/mcp/tools.ts):

// Already implemented: get_cart, add_to_cart
tools.set('get_cart', createTool('get_cart', {...}));
tools.set('add_to_cart', createTool('add_to_cart', {...}));

// NEEDED: quantity update, remove, clear, coupon

Orders Tools

Tool	Existing Code	Location	Status	Gap/Action
`orders.create_from_cart`	❌	-	NEW	Create order from cart
`orders.get`	✅	`lib/mcp/tools.ts:60-97`	READY	Returns order details
`orders.list`	✅	`lib/mcp/tools.ts:99-131`	READY	With status filter
`orders.cancel`	❌	-	NEW	Add cancel logic
`orders.refund`	⚠️	`lib/mcp/tools.ts:214-252`	PARTIAL	Create refund, needs Stripe

Existing Orders Code:

// Already implemented: get_order, list_orders
tools.set('get_order', createTool('get_order', {...}));
tools.set('list_orders', createTool('list_orders', {...}));

// NEEDED: create_from_cart, cancel, full refund

Search Tools

Tool	Existing Code	Location	Status	Gap/Action
`catalog.search`	⚠️	`lib/mcp/tools.ts:158-210`	PARTIAL	Has `search_products`
`catalog.autocomplete`	❌	-	NEW	Add OpenSearch suggester
`catalog.recommendations`	❌	-	NEW	Use hybrid search

Existing Search Code (lib/search/hybrid.ts):

// FULLY IMPLEMENTED: hybrid search with BM25 + pgvector RRF
export async function hybridSearch(params: {...}) {...}
export async function searchProducts(query: string, options: {...}) {...}
export async function searchWithPreferences(query: string, userId: string) {...}

Refund Tools

Tool	Existing Code	Location	Status	Gap/Action
`refunds.create`	✅	`lib/agents/refund.ts`	READY	Full refund workflow
`refunds.get`	✅	`lib/mcp/tools.ts:254-282`	READY	Status check

Existing Refund Code:

lib/agents/refund.ts - Agent for refund processing
lib/stripe/client.ts - Full Stripe SDK with types
lib/stripe/refund.ts - Refund webhook handler

Phase 3: UCP as Backbone

Component	Existing Code	Location	Status	Gap/Action
UCP Types	✅	`lib/ucp/types.ts`	MOCK	Extend with real actions
UCP Protocol	✅	`lib/ucp/protocol.ts`	MOCK	Connect to real tools
Schema.org Schemas	✅	`lib/schemas/commerce.ts`	READY	631 lines of Zod schemas!

Existing UCP Code (lib/ucp/types.ts):

// Already defined:
export interface UCPOffer {...}
export interface UCPPayment {...}
export interface UCPOrder {...}
export interface UCPCustomer {...}

// NEEDED: Add UCPMessage with actions
export type UCPAction = 
  | 'SEARCH_PRODUCTS' | 'ADD_TO_CART' | 'CREATE_CHECKOUT' ...

Existing Schema.org Schemas (lib/schemas/commerce.ts:631):

// FULLY IMPLEMENTED - 631 lines of schemas!
export const ProductSchema = z.object({...})
export const OrderSchema = z.object({...})
export const RefundSchema = z.object({...})
export const ShoppingCartSchema = z.object({...})
export const SupportTicketSchema = z.object({...})

Phase 4: Stripe via MCP

Component	Existing Code	Location	Status	Gap/Action
Stripe Client	✅	`lib/stripe/client.ts`	READY	Full typed SDK wrapper
Refund Logic	✅	`lib/stripe/refund.ts`	READY	Webhook handling
Create Checkout	❌	-	NEW	Add checkout session tool
Payment Intent	❌	-	NEW	Add payment intent tool

Existing Stripe Code (lib/stripe/client.ts:339):

// FULLY IMPLEMENTED:
export async function createRefund(params: CreateRefundParams): Promise<RefundResult> {...}
export async function getRefund(refundId: string): Promise<RefundResult> {...}
export async function getPaymentIntent(paymentIntentId: string): Promise<PaymentIntentInfo> {...}
export function verifyWebhookSignature(payload: string | Buffer, signature: string): Stripe.Event {...}
export function calculateRefundableAmount(paymentIntent: PaymentIntentInfo): number {...}
export function isRefundable(paymentIntent: PaymentIntentInfo): boolean {...}