shopify-theme-devtools 2.2.1 → 2.3.2

package/README.md

@@ -24,13 +24,15 @@ A powerful in-browser developer tools panel for Shopify theme development. Inspe
 
 ### Core Panels
 
+- **AI Assistant** — GPT-powered theme debugging with full context access (cart, metafields, analytics, accessibility, and more)
 - **Objects Inspector** — Browse `shop`, `product`, `collection`, `customer`, `cart` and more with deep search and collapsible tree view
 - **Metafields Viewer** — Explore metafields across all resources and namespaces with type labels
 - **Cart Panel** — Real-time cart state with add/remove/quantity controls, cart history with restore, and attribute editing
 - **Console** — Chrome DevTools-style console with Liquid expression evaluator, and autocomplete
 - **Localization** — Markets, currencies, languages, and country data with quick switcher
 - **SEO Inspector** — Meta tags, Open Graph, Twitter Cards, and structured data (JSON-LD) validation
-- **Analytics Viewer** — Detects Google Analytics, Facebook Pixel, and other tracking codes
+- **Analytics Viewer** — Captures GA4, Facebook Pixel, TikTok, Pinterest, Snapchat, Klaviyo, Shopify Analytics, and dataLayer events
+- **Accessibility Scanner** — WCAG compliance checker with issue severity, suggested fixes, and score
 - **Storage Inspector** — Browse and edit localStorage, sessionStorage, and cookies
 - **Apps Panel** — Lists installed Shopify apps detected on the page
 - **Info Panel** — Theme details, template info, and request metadata
@@ -96,6 +98,72 @@ The Console panel includes an interactive expression evaluator for testing Liqui
 - **Cart History** — View previous cart states with timestamps and restore any snapshot
 - **Attribute Editor** — Modify cart attributes and notes
 - **Diff View** — See what changed between cart states
+- **Scenario Builder** — Create and save cart scenarios for quick testing
+- **Cart Tests** — Write validation rules to automatically test cart items
+
+### Cart Tests
+
+The Cart Tests feature lets you create custom validation rules to ensure cart items meet your business requirements. Tests can be run manually or automatically whenever the cart changes.
+
+**Rule Types:**
+
+| Type | Description | Example |
+|------|-------------|---------|
+| **Property Dependency** | If item has property X, must have properties Y, Z | GWP items require `_gwp_price` and `_gwp_source` |
+| **Field Value** | If field equals X, another field must meet condition | Gift Cards must have quantity = 1 |
+| **Cart Composition** | If item X exists, item Y must also exist | Electronics require warranty item |
+| **Quantity** | Min/max/multiple constraints per-item or cart-total | Max 10 per item, cart total max 50 |
+
+**Features:**
+
+- **Pre-built Templates** — 16 ready-to-use templates for common scenarios
+- **Auto-run** — Toggle to run all tests whenever cart changes
+- **Import/Export** — Save and share test configurations as JSON
+- **Inline Results** — Pass/fail badges show test status at a glance
+
+### AI Assistant
+
+An intelligent GPT-powered assistant that understands your Shopify theme context. Ask questions, debug issues, and generate Liquid code with full access to your page data.
+
+**Setup:**
+1. Open the AI panel
+2. Enter your OpenAI API key (stored locally, never sent anywhere except OpenAI)
+3. Start asking questions
+
+**What AI Can Access:**
+- Page/template info, shop details, current resource (product/collection/page)
+- Customer data (if logged in)
+- Cart state and cart history
+- Metafields for all resources
+- Section schemas (from theme editor data)
+- HTML structure of the page
+- Network requests and responses
+- Cookies, localStorage, sessionStorage
+- Liquid errors detected on the page
+- Accessibility scan results
+- Analytics events (GA4, Facebook Pixel, TikTok, Pinterest, Snapchat, Klaviyo, Shopify, dataLayer)
+
+**Context Modes:**
+| Mode | Description |
+|------|-------------|
+| **Auto** | Smart detection - includes relevant context based on your question |
+| **Minimal** | Basic page info and cart only (faster responses) |
+| **Full** | Everything including cookies, storage, analytics, accessibility |
+| **Custom** | Pick exactly which context to include |
+
+**Example Questions:**
+- "What data is available on this page?"
+- "Help me write Liquid to display the product price with compare at price"
+- "Why isn't my add to cart button working?"
+- "What analytics events are firing on this page?"
+- "Are there any accessibility issues I should fix?"
+
+**Features:**
+- **Streaming responses** — See answers as they're generated
+- **Syntax highlighting** — Code blocks with Liquid, JavaScript, and JSON highlighting
+- **Conversation history** — Per-page conversations persist in session storage
+- **Search** — Find text across your conversation history
+- **Copy code** — One-click copy for any code block
 
 ### Liquid Error Detection
 
@@ -107,6 +175,33 @@ Automatically scans the page for common Liquid issues:
 - Schema validation errors
 - Deprecation warnings
 
+### Analytics Panel
+
+Captures and inspects analytics events from multiple tracking providers in real-time.
+
+**Supported Providers:**
+| Provider | Detection |
+|----------|-----------|
+| **Google Analytics 4** | `gtag()` calls |
+| **Google Analytics Universal** | `ga()` calls |
+| **Facebook Pixel** | `fbq()` calls |
+| **TikTok Pixel** | `ttq.track()` calls |
+| **Pinterest Tag** | `pintrk()` calls |
+| **Snapchat Pixel** | `snaptr()` calls |
+| **Klaviyo** | `_learnq.push()` calls |
+| **Shopify Analytics** | `Shopify.analytics.publish()` |
+| **Shopify Web Pixels** | `analytics.subscribe()` |
+| **DataLayer** | `dataLayer.push()` |
+
+**Features:**
+- **Live capture** — Events appear as they fire
+- **Conversion tracking** — Highlights purchase, add_to_cart, and other conversion events
+- **Filtering** — Filter by provider or search event names/data
+- **Deduplication** — Groups duplicate events fired within 500ms
+- **Export** — Download captured events as JSON
+- **Pause/Resume** — Stop capturing to analyze current events
+- **Persistence** — Events persist across page navigations (session storage)
+
 ### Network Panel
 
 Captures and inspects Shopify API requests with powerful debugging tools:
@@ -163,6 +258,16 @@ npx shopify-theme-devtools init --inject
 | `--inject` | Automatically add render tag to `layout/theme.liquid` |
 | `--force` | Overwrite existing files without prompting |
 
+The CLI automatically detects and injects your `metafields.json` schema from `.shopify/metafields.json` (or theme root), enabling devtools to show all defined metafields.
+
+#### Syncing Metafields
+
+When your metafields change over time, run the sync command to update the schema without overwriting other customizations:
+
+```bash
+npx shopify-theme-devtools sync
+```
+
 ```bash
 # Examples
 npx shopify-theme-devtools init                    # Uses CDN (recommended)
@@ -200,11 +305,13 @@ The devtools panel automatically appears on **unpublished/development themes onl
 
 | Panel | Description |
 |-------|-------------|
+| **AI** | GPT-powered assistant with full theme context access |
 | **Objects** | Inspect all Liquid objects with search and tree navigation |
 | **Metafields** | Browse metafields by resource (product, collection, shop, etc.) |
-| **Cart** | Live cart state, history snapshots, and manipulation tools |
+| **Cart** | Live cart state, history, scenarios, tests, and manipulation tools |
 | **Locale** | Markets, currencies, languages with locale switching |
-| **Analytics** | Detected tracking codes and analytics configuration |
+| **Analytics** | Live event capture for GA4, FB Pixel, TikTok, Pinterest, Klaviyo, Shopify |
+| **Accessibility** | WCAG compliance scanner with score and suggested fixes |
 | **SEO** | Meta tags, Open Graph, Twitter Cards, JSON-LD structured data |
 | **Apps** | Installed Shopify apps detected on the page |
 | **Network** | API request monitor with edit/replay, cart diffs, and error diagnosis |
@@ -284,11 +391,17 @@ src/
 │   ├── components/
 │   │   ├── theme-devtools.js         # Main component with tab management
 │   │   ├── object-inspector.js       # Tree view inspector
-│   │   └── panels/                   # Panel components
+│   │   └── panels/                   # Panel components (ai, cart, analytics, etc.)
+│   ├── lib/
+│   │   └── cart-test-templates.js    # Pre-built cart test templates
 │   ├── services/
+│   │   ├── ai.js                     # OpenAI API integration
+│   │   ├── analytics.js              # Analytics event interceptor
+│   │   ├── accessibility.js          # Accessibility scanning service
 │   │   ├── cart.js                   # Cart API with history
 │   │   ├── product.js                # Product API (variants/images)
 │   │   ├── context.js                # Liquid context parser
+│   │   ├── context-serializer.js     # AI context serialization
 │   │   ├── expression-evaluator.js   # Liquid expression engine
 │   │   ├── network-interceptor.js    # Fetch/XHR interceptor with persistence
 │   │   └── settings.js               # User preferences

package/bin/cli.js

@@ -47,6 +47,7 @@ ${COLORS.bold}Usage:${COLORS.reset}
 
 ${COLORS.bold}Commands:${COLORS.reset}
   init          Initialize devtools in your Shopify theme
+  sync          Sync metafields schema from .shopify/metafields.json
 
 ${COLORS.bold}Options for init:${COLORS.reset}
   --local       Copy JS/CSS to assets folder instead of using CDN
@@ -58,6 +59,7 @@ ${COLORS.bold}Examples:${COLORS.reset}
   npx shopify-theme-devtools init
   npx shopify-theme-devtools init --local
   npx shopify-theme-devtools init --local --inject
+  npx shopify-theme-devtools sync
 `);
 }
 
@@ -77,6 +79,57 @@ function copyFile(src, dest, force = false) {
   return true;
 }
 
+function findMetafieldsSchema(themeRoot) {
+  // Look for metafields.json in common locations
+  const possiblePaths = [
+    join(themeRoot, '.shopify', 'metafields.json'),
+    join(themeRoot, 'metafields.json'),
+    join(themeRoot, 'config', 'metafields.json'),
+  ];
+
+  for (const schemaPath of possiblePaths) {
+    if (existsSync(schemaPath)) {
+      try {
+        const content = readFileSync(schemaPath, 'utf-8');
+        // Validate it's valid JSON
+        JSON.parse(content);
+        return { path: schemaPath, content };
+      } catch {
+        // Invalid JSON, skip
+      }
+    }
+  }
+
+  return null;
+}
+
+function injectMetafieldsSchema(liquidContent, schemaContent) {
+  // Replace the default empty schema with the actual schema
+  const defaultSchema = `{%- capture devtools_metafields_schema -%}
+{
+  "article": [],
+  "blog": [],
+  "collection": [],
+  "company": [],
+  "company_location": [],
+  "location": [],
+  "market": [],
+  "order": [],
+  "page": [],
+  "product": [],
+  "variant": [],
+  "shop": [],
+  "customer": []
+}
+{%- endcapture -%}`;
+
+  const newSchema = `{%- capture devtools_metafields_schema -%}
+${schemaContent.trim()}
+{%- endcapture -%}`;
+
+  return liquidContent.replace(defaultSchema, newSchema);
+}
+
 function patchLiquidForLocal(content) {
   // Change CDN to asset_url
   let patched = content.replace(
@@ -198,6 +251,13 @@ async function init(args) {
     '{%- assign devtools_local = false -%}'
   );
 
+  // Auto-detect and inject metafields schema
+  const metafieldsSchema = findMetafieldsSchema(themeRoot);
+  if (metafieldsSchema) {
+    liquidContent = injectMetafieldsSchema(liquidContent, metafieldsSchema.content);
+    success(`Injected metafields schema from ${metafieldsSchema.path.replace(themeRoot + '/', '')}`);
+  }
+
   if (useLocal) {
     liquidContent = patchLiquidForLocal(liquidContent);
   }
@@ -255,6 +315,67 @@ async function init(args) {
   console.log();
 }
 
+async function sync() {
+  const cwd = process.cwd();
+
+  console.log();
+  log('Shopify Theme Devtools', COLORS.bold);
+  console.log();
+
+  // Detect theme root
+  const themeRoot = detectThemeRoot(cwd);
+
+  if (!themeRoot) {
+    error('Could not detect Shopify theme directory');
+    info('Make sure you run this command from your theme root');
+    info('(should contain layout/, snippets/, templates/ folders)');
+    process.exit(1);
+  }
+
+  const snippetsDir = join(themeRoot, 'snippets');
+  const liquidDest = join(snippetsDir, 'theme-devtools-bridge.liquid');
+
+  // Check if snippet exists
+  if (!existsSync(liquidDest)) {
+    error('Devtools snippet not found');
+    info('Run "npx shopify-theme-devtools init" first');
+    process.exit(1);
+  }
+
+  // Find metafields schema
+  const metafieldsSchema = findMetafieldsSchema(themeRoot);
+
+  if (!metafieldsSchema) {
+    error('No metafields.json found');
+    info('Looked in: .shopify/metafields.json, metafields.json, config/metafields.json');
+    process.exit(1);
+  }
+
+  // Read current snippet
+  let liquidContent = readFileSync(liquidDest, 'utf-8');
+
+  // Replace the metafields schema using a regex that matches any JSON content
+  const schemaRegex = /\{%- capture devtools_metafields_schema -%\}[\s\S]*?\{%- endcapture -%\}/;
+
+  if (!schemaRegex.test(liquidContent)) {
+    error('Could not find metafields schema section in snippet');
+    info('The snippet may be corrupted. Run "npx shopify-theme-devtools init --force" to regenerate');
+    process.exit(1);
+  }
+
+  const newSchema = `{%- capture devtools_metafields_schema -%}
+${metafieldsSchema.content.trim()}
+{%- endcapture -%}`;
+
+  liquidContent = liquidContent.replace(schemaRegex, newSchema);
+
+  // Write updated snippet
+  writeFileSync(liquidDest, liquidContent);
+  success(`Synced metafields schema from ${metafieldsSchema.path.replace(themeRoot + '/', '')}`);
+
+  console.log();
+}
+
 // Parse arguments
 const args = process.argv.slice(2);
 const command = args[0];
@@ -266,6 +387,8 @@ if (!command || command === '--help' || command === '-h') {
 
 if (command === 'init') {
   init(args);
+} else if (command === 'sync') {
+  sync();
 } else {
   error(`Unknown command: ${command}`);
   printHelp();