pre-commit-analysis

name	pre-commit-analysis
description	Pre-commit implementation analysis for Retail-Agentic-Commerce. Use before commits, after significant changes, or when validating Apps SDK tools, mock data, MCP communication, widget isolation, or implementation quality.

Pre-Commit Analysis

Use this skill before committing significant changes or when the user asks for implementation-quality validation.

If multi-agent tools are available, run the analysis areas in parallel. If not, perform the same checks directly with local commands.

Analysis Areas

1. MCP tools: verify tool implementations use real APIs or shared data sources.
2. Apps SDK web isolation: verify widget code communicates through postMessage and MCP boundaries.
3. Mock data completeness: verify mock data exists and stays synchronized with the shared catalog.
4. Communication flow: verify message types and handlers match across parent UI and widget code.

MCP Tools Verification

Files to inspect:

• src/apps_sdk/tools/*.py
• src/apps_sdk/main.py

Red flags:

• Hardcoded product lists instead of shared catalog data.
• Hardcoded responses where API calls or shared services are expected.
• Mock data drifting from src/data/product_catalog.py.
• Missing error handling for API failures.

Commands:

rg "MOCK_PRODUCTS|mock_products" src/apps_sdk/
rg "from src.data.product_catalog import" src/apps_sdk/
rg "httpx|requests|fetch" src/apps_sdk/tools/

Expected patterns:

from src.data.product_catalog import PRODUCTS

async with httpx.AsyncClient() as client:
    response = await client.get(f"{merchant_url}/products/{id}")

Apps SDK Web Isolation

Files to inspect:

• src/apps_sdk/web/src/**/*.tsx
• src/apps_sdk/web/src/**/*.ts
• src/apps_sdk/web/package.json

Red flags:

• Imports from parent UI directories.
• Direct calls to localhost backend ports from widget code.
• Shared state with the parent app.
• Direct window.parent usage except for postMessage.

Commands:

rg "from ['\"]\\.\\./\\.\\./\\.\\." src/apps_sdk/web/src/
rg "localhost:8000|localhost:8001" src/apps_sdk/web/src/
rg "postMessage|window\\.parent" src/apps_sdk/web/src/

Expected pattern:

window.parent.postMessage({ type: "GET_RECOMMENDATIONS" }, "*");
const result = await window.openai.callTool("add-to-cart", args);

Mock Data Completeness

Files to inspect:

• src/data/product_catalog.py
• src/ui/data/mock-data.ts
• src/apps_sdk/tools/recommendations.py

Red flags:

• Product count mismatch.
• Missing development or test mock data.
• Hardcoded data instead of catalog imports.
• Missing fallbacks when agent services are unavailable.

Commands:

rg '"id": "prod_' src/data/product_catalog.py | wc -l
rg "CATALOG_PRODUCTS|from src.data.product_catalog" src/apps_sdk/

Communication Flow

Files to inspect:

• src/ui/components/agent/MerchantIframeContainer.tsx
• src/ui/hooks/useMCPClient.ts
• src/apps_sdk/web/src/App.tsx
• src/apps_sdk/web/src/main.tsx

Message types to verify:

Direction	Message Type	Purpose
Widget to Parent	GET_RECOMMENDATIONS	Request product recommendations
Parent to Widget	RECOMMENDATIONS_RESULT	Return recommendation data
Widget to Parent	CHECKOUT_COMPLETE	Notify checkout success
Widget to Parent	CALL_TOOL	MCP tool invocation through the bridge

Commands:

rg "message\\.type.*==|case.*:" src/ui/components/agent/MerchantIframeContainer.tsx
rg "postMessage.*type:" src/apps_sdk/web/src/

Validation Checklist

Track these before committing:

Pre-Commit Analysis:
- [ ] MCP tools use shared catalog data where applicable.
- [ ] MCP tools make real API calls where needed.
- [ ] Apps SDK web has no forbidden parent imports.
- [ ] Widget uses postMessage for parent communication.
- [ ] Widget makes no direct backend API calls.
- [ ] Mock data is synced with product catalog expectations.
- [ ] Agent fallbacks exist when services are unavailable.
- [ ] Message types match between sender and receiver.
- [ ] Relevant tests pass.
- [ ] Relevant linter and type checks pass.

Post-Analysis Commands

Run relevant checks for the changed areas:

uv run pytest tests/apps_sdk/ -v
uv run ruff check src/apps_sdk/
uv run pyright src/apps_sdk/
cd src/apps_sdk/web && pnpm build

Broaden to the full quality gates from skills/features/SKILL.md and skills/ui/SKILL.md when shared backend or frontend behavior changed.

Report Format

## Pre-Commit Analysis Report

### MCP Tools
- Status: PASS/FAIL
- Issues: [list any issues]

### Apps SDK Isolation
- Status: PASS/FAIL
- Issues: [list any issues]

### Mock Data
- Status: PASS/FAIL
- Product count: X/17
- Issues: [list any issues]

### Communication Flow
- Status: PASS/FAIL
- Issues: [list any issues]

### Recommendations
1. [High priority fixes]
2. [Medium priority improvements]
3. [Low priority enhancements]