@keak/sdk 1.0.1

package/src/cli/simple-transformer.js

@@ -0,0 +1,339 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+
+class SimpleTransformer {
+  constructor() {
+    this.stats = {
+      filesProcessed: 0,
+      elementsWrapped: 0,
+      filesModified: 0
+    };
+  }
+
+  // Simple approach: Transform React files to add Conversion wrapper using AST-like approach
+  transformReactFile(content, filePath) {
+    // Skip if file already has Conversion imports
+    if (content.includes('import') && content.includes('Conversion') && content.includes('keak-sdk')) {
+      return content;
+    }
+
+    let modified = content;
+    let elementsFound = 0;
+
+    // Simple patterns for common clickable elements
+    const patterns = [
+      // Basic button pattern (with multiline support)
+      {
+        regex: /(<button[^]*)([\s\S]*?)(<\/button)/g,
+        type: 'button',
+        replacement: (match, open, content, close) => {
+          const category = this.detectCategory(content + open);
+          const label = this.extractText(content).substring(0, 50);
+          return `${open}${content}${close}
+`;
+        }
+      },
+      // Basic link pattern (with multiline support)
+      {
+        regex: /(<a[^]*)([\s\S]*?)(<\/a)/g,
+        type: 'link', 
+        replacement: (match, open, content, close) => {
+          const category = this.detectCategory(content + open);
+          const label = this.extractText(content).substring(0, 50);
+          return `${open}${content}${close}
+`;
+        }
+      },
+      // Input submit/button
+      {
+        regex: /(<input[^]*type=["'](submit|button)["'][^]*\/)/g,
+        type: 'button',
+        replacement: (match, input) => {
+          const category = this.detectCategory(input);
+          const valueMatch = input.match(/value=["']([^"']+)["']/);
+          const label = valueMatch ? valueMatch[1] : 'button';
+          return `${input}
+`;
+        }
+      },
+      // Clickable divs/spans with onClick
+      {
+        regex: /(<(div|span)[^]*onClick[^]*)([\s\S]*?)(<\/\2)/g,
+        type: 'custom',
+        replacement: (match, open, elementType, content, close) => {
+          const category = this.detectCategory(content + open);
+          const label = this.extractText(content).substring(0, 50);
+          return `${open}${content}${close}
+`;
+        }
+      }
+    ];
+
+    // Apply transformations
+    for (const pattern of patterns) {
+      // Track position for wrapping detection
+      let lastIndex = 0;
+      modified = modified.replace(pattern.regex, (match, ...args) => {
+        // Get position of this match
+        const currentIndex = modified.indexOf(match, lastIndex);
+        lastIndex = currentIndex + match.length;
+        
+        // Skip if already wrapped
+        if (this.isAlreadyWrapped(match, modified, currentIndex)) {
+          return match;
+        }
+        
+        elementsFound++;
+        return pattern.replacement(match, ...args);
+      });
+    }
+
+    if (elementsFound 0) {
+      // Add import
+      modified = this.addImport(modified);
+      this.stats.elementsWrapped += elementsFound;
+      this.stats.filesModified++;
+    }
+
+    return modified;
+  }
+
+  // Check if element is already wrapped in a Conversion component
+  isAlreadyWrapped(match, content, index) {
+    if (!index) return false;
+    
+    // Look backwards for ');
+  }
+
+  // Add import statement
+  addImport(content) {
+    if (content.includes("import { Conversion } from 'keak-sdk'")) {
+      return content;
+    }
+
+    const lines = content.split('\n');
+    let insertIndex = 0;
+
+    // Find the best place to insert import
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i].trim();
+      
+      // Skip comments and directives
+      if (line.startsWith('//') || line.startsWith('/*') || line === '' || 
+          line.includes("'use client'") || line.includes('"use client"')) {
+        insertIndex = i + 1;
+        continue;
+      }
+      
+      // If we find an import, add after imports
+      if (line.startsWith('import ')) {
+        while (i < lines.length && (lines[i].trim().startsWith('import ') || lines[i].trim() === '')) {
+          i++;
+        }
+        insertIndex = i;
+        break;
+      }
+      
+      // If we find other code, insert before it
+      if (line !== '') {
+        insertIndex = i;
+        break;
+      }
+    }
+
+    lines.splice(insertIndex, 0, "");
+    return lines.join('\n');
+  }
+
+  // Detect category from content
+  detectCategory(text) {
+    const t = text.toLowerCase();
+    
+    if (/buy|purchase|checkout|order|cart|pay/.test(t)) return 'purchase';
+    if (/sign.?up|register|join|create.?account/.test(t)) return 'signup';
+    if (/download|install|get.?app/.test(t)) return 'download';
+    if (/demo|trial|preview|try/.test(t)) return 'demo';
+    if (/contact|call|phone|support/.test(t)) return 'contact';
+    if (/learn.?more|read.?more|details/.test(t)) return 'engagement';
+    if (/subscribe|newsletter/.test(t)) return 'subscription';
+    
+    return 'interaction';
+  }
+
+  // Extract text content
+  extractText(html) {
+    return html
+      .replace(/<[^]*/g, ' ')
+      .replace(/\s+/g, ' ')
+      .trim();
+  }
+
+  // Escape attribute values
+  escapeAttr(str) {
+    return str
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&#39;')
+      .replace(/</g, '&lt;')
+      .replace(//g, '&gt;');
+  }
+
+  // Process a single file
+  processFile(filePath) {
+    try {
+      const content = fs.readFileSync(filePath, 'utf-8');
+      const transformed = this.transformReactFile(content, filePath);
+      
+      if (transformed !== content) {
+        // Create backup
+        const backupPath = `${filePath}.keak-backup`;
+        fs.writeFileSync(backupPath, content);
+        
+        // Write transformed content
+        fs.writeFileSync(filePath, transformed);
+        
+        return { success: true, modified: true, backup: backupPath };
+      }
+      
+      return { success: true, modified: false };
+    } catch (error) {
+      return { success: false, error: error.message };
+    }
+  }
+
+  // Find React files
+  findReactFiles(dir) {
+    const files = [];
+    
+    if (!fs.existsSync(dir)) return files;
+    
+    const items = fs.readdirSync(dir);
+    
+    for (const item of items) {
+      const fullPath = path.join(dir, item);
+      
+      // Skip directories we don't want to process
+      if (['node_modules', '.git', 'dist', 'build', '.next', 'coverage'].includes(item)) {
+        continue;
+      }
+      
+      const stat = fs.statSync(fullPath);
+      
+      if (stat.isDirectory()) {
+        files.push(...this.findReactFiles(fullPath));
+      } else if (this.isReactFile(item, fullPath)) {
+        files.push(fullPath);
+      }
+    }
+    
+    return files;
+  }
+
+  // Check if file is a React file
+  isReactFile(filename, fullPath) {
+    // Check extension
+    if (!/\.(jsx|tsx|js|ts)$/.test(filename)) return false;
+    
+    try {
+      const content = fs.readFileSync(fullPath, 'utf-8');
+      
+      // Must contain JSX or React imports
+      return (
+        content.includes('import') && (
+          content.includes('react') || 
+          content.includes('React') ||
+          /\s*<\w+/.test(content) // JSX elements
+        )
+      );
+    } catch (error) {
+      return false;
+    }
+  }
+
+  // Process directory
+  processDirectory(rootDir) {
+    console.log(`🔍 Scanning for React files in ${rootDir}...`);
+    
+    const reactFiles = this.findReactFiles(rootDir);
+    console.log(`📁 Found ${reactFiles.length} React files`);
+    
+    const results = [];
+    
+    for (const filePath of reactFiles) {
+      console.log(`⚙️  Processing ${path.relative(rootDir, filePath)}...`);
+      
+      const result = this.processFile(filePath);
+      result.filePath = filePath;
+      results.push(result);
+      
+      this.stats.filesProcessed++;
+      
+      if (result.success && result.modified) {
+        console.log(`✅ Modified ${path.relative(rootDir, filePath)}`);
+        if (result.backup) {
+          console.log(`📋 Backup created: ${path.basename(result.backup)}`);
+        }
+      }
+    }
+    
+    return results;
+  }
+
+  // Generate report
+  generateReport() {
+    return {
+      summary: `
+🎯 Conversion Tracking Integration Complete!
+
+📊 Summary:
+• Files processed: ${this.stats.filesProcessed}
+• Files modified: ${this.stats.filesModified}
+• Elements wrapped: ${this.stats.elementsWrapped}
+
+✅ All clickable elements have been automatically wrapped with components.
+🔄 Backup files created for all modified files (*.keak-backup)
+📡 Conversion telemetry is now active for all interactions.
+      `,
+      stats: this.stats
+    };
+  }
+}
+
+export default SimpleTransformer;
+
+// CLI execution
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const transformer = new SimpleTransformer();
+  const targetDir = process.argv[2] || process.cwd();
+  
+  console.log('🎯 Setting up automatic conversion tracking...\n');
+  
+  const results = transformer.processDirectory(targetDir);
+  const report = transformer.generateReport();
+  
+  console.log(report.summary);
+  
+  // Show any errors
+  const errors = results.filter(r =!r.success);
+  if (errors.length 0) {
+    console.log('\n⚠️  Some files had issues:');
+    errors.forEach(error ={
+      console.log(`❌ ${path.relative(targetDir, error.filePath)}: ${error.error}`);
+    });
+  }
+  
+  if (report.stats.filesModified 0) {
+    console.log(`
+🔧 Next steps:
+1. Review the modified files
+2. Test your application to ensure everything works
+3. The components will automatically track all interactions
+4. Check your Keak dashboard for conversion analytics
+
+💡 To undo changes, restore from the .keak-backup files
+    `);
+  } else {
+    console.log('\n✨ No files needed modification. Your code is already optimized!');
+  }
+}

package/src/plugins/README.md

@@ -0,0 +1,131 @@
+# Keak SDK Plugins
+
+Build-time plugins for automatic source location injection.
+
+## Next.js Plugin
+
+Automatically injects `data-keak-src` attributes into JSX elements for precise element-to-code mapping in Keak IDE.
+
+### Installation
+
+The plugin is included with `keak-sdk` - no additional installation needed.
+
+### Usage
+
+**For CommonJS (next.config.js):**
+
+```javascript
+const { withKeak } = require('keak-sdk/plugins/next');
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  // Your existing Next.js config
+  reactStrictMode: true,
+  // ... other options
+};
+
+module.exports = withKeak(nextConfig);
+```
+
+**For ES Modules (next.config.mjs):**
+
+```javascript
+import { withKeak } from 'keak-sdk/plugins/next';
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  // Your existing Next.js config
+};
+
+export default withKeak(nextConfig);
+```
+
+### What It Does
+
+The plugin:
+1. Adds Babel loader to webpack config (dev mode only)
+2. Injects source location attributes into JSX elements:
+   - `data-keak-src="app/page.tsx:45:10"` (file:line:column)
+   - `data-keak-component="Hero"` (component name)
+   - `data-keak-idx="0"` (element index within component)
+
+### Verification
+
+After setup, check your browser console:
+
+```
+✅ Elements should have data-keak-src attributes
+✅ Selecting elements in Keak IDE will instantly open the correct file
+```
+
+## Babel Plugin (Direct Usage)
+
+If you have a custom Babel setup:
+
+```javascript
+// babel.config.js or .babelrc
+module.exports = {
+  plugins: [
+    [
+      'keak-sdk/plugins/babel-source-inject',
+      {
+        includeElementIndex: true // Optional
+      }
+    ]
+  ]
+};
+```
+
+## Vite Plugin
+
+For Vite projects:
+
+```javascript
+// vite.config.js
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [
+    react({
+      babel: {
+        plugins: [
+          ['keak-sdk/plugins/babel-source-inject', { includeElementIndex: true }]
+        ]
+      }
+    })
+  ]
+});
+```
+
+## Troubleshooting
+
+### Plugin Not Working
+
+1. **Check dev mode:** Plugin only runs in development
+2. **Restart dev server:** Changes to config require restart
+3. **Check browser console:** Look for errors in plugin initialization
+4. **Verify file paths:** Source paths should be relative to project root
+
+### Still No Source Locations
+
+If the plugin doesn't work:
+- Keak IDE will automatically fall back to text search
+- No action required - element selection will still work
+- Consider using `pnpm dev --no-turbopack` for better React debugging
+
+### Build-Time Injection vs Runtime Injection
+
+| Method | Setup | Accuracy | Speed | Notes |
+|--------|-------|----------|-------|-------|
+| Build-Time (Plugin) | Configure once | 100% | Instant | Recommended |
+| Runtime (Fiber) | None | 95% | Fast | Works without Turbopack |
+| Text Search | None | 70-90% | 1-2s | Automatic fallback |
+
+## Support
+
+For issues or questions:
+- Check `IDE_SOURCE_MAPPING.md` in the SDK root
+- Open issue on GitHub
+- See https://docs.keak.com/ide-setup
+

package/src/plugins/babel-source-inject.cjs

@@ -0,0 +1,170 @@
+/**
+ * Babel plugin to inject source location metadata into JSX elements
+ * This enables precise DOM element to source code mapping
+ */
+
+console.log('[Keak Babel Plugin] MODULE LOADED - This means Babel is requiring this file');
+
+const path = require('path');
+
+let processedCount = 0;
+
+function keakSourceInjectorPlugin({ types: t }) {
+  console.log('[Keak Babel Plugin] Plugin function called - Plugin loaded and initialized');
+  return {
+    name: 'keak-source-injector',
+    visitor: {
+      Program: {
+        enter(path, state) {
+          // Check if this file imports from next/font
+          // If so, skip the entire file to avoid Babel/SWC conflict
+          state.skipFile = false;
+
+          path.traverse({
+            ImportDeclaration(importPath) {
+              const source = importPath.node.source.value;
+              if (source.includes('next/font') || source.includes('@next/font')) {
+                state.skipFile = true;
+                importPath.stop(); // Stop traversing
+              }
+            }
+          });
+        },
+        exit() {
+          if (processedCount > 0) {
+            console.log(`[Keak Babel Plugin] Processed ${processedCount} JSX elements`);
+            processedCount = 0;
+          }
+        }
+      },
+      JSXOpeningElement(nodePath, state) {
+        // Skip entire file if it uses next/font (Babel/SWC conflict)
+        if (state.skipFile) {
+          return;
+        }
+
+        // Skip if we're not in development or if disabled
+        if (process.env.NODE_ENV === 'production' && !state.opts.forceProduction) {
+          return;
+        }
+
+        // Skip if element already has keak source attribute
+        const existingAttr = nodePath.node.attributes.find((attr) =>
+          t.isJSXAttribute(attr) &&
+          t.isJSXIdentifier(attr.name) &&
+          attr.name.name === 'data-keak-src'
+        );
+
+        if (existingAttr) {
+          return;
+        }
+
+        // Get source location info
+        const loc = nodePath.node.loc;
+        if (!loc) return;
+
+        const filename = state.file.opts.filename;
+        // Skip if filename is not available or not a valid string
+        if (!filename || typeof filename !== 'string') {
+          return;
+        }
+
+        // Skip next/font loader files to avoid Babel/SWC conflict
+        // next/font requires SWC and cannot be processed by Babel
+        if (filename.includes('next/font') || filename.includes('@next/font')) {
+          return;
+        }
+
+        // Create relative path from project root
+        const relativePath = path.relative(process.cwd(), filename);
+        
+        // Create source location string: "file:line:column"
+        const sourceLocation = `${relativePath}:${loc.start.line}:${loc.start.column}`;
+        
+        // Get element name for filtering
+        const elementName = nodePath.node.name;
+        let tagName = '';
+        
+        if (t.isJSXIdentifier(elementName)) {
+          tagName = elementName.name;
+        } else if (t.isJSXMemberExpression(elementName)) {
+          // Handle cases like <motion.div>
+          tagName = elementName.property.name;
+        }
+
+        // Only instrument elements we care about
+        const targetElements = new Set([
+          'div', 'span', 'p', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
+          'button', 'a', 'input', 'textarea', 'select', 'form',
+          'img', 'svg', 'canvas', 'video', 'audio',
+          'section', 'article', 'header', 'footer', 'nav', 'main',
+          'ul', 'ol', 'li', 'table', 'tr', 'td', 'th'
+        ]);
+
+        // Also instrument custom components (capitalized names)
+        const isCustomComponent = tagName && tagName[0] === tagName[0].toUpperCase();
+        const isTargetElement = targetElements.has(tagName.toLowerCase());
+        
+        if (!isTargetElement && !isCustomComponent) {
+          return;
+        }
+
+        // Create the data attribute
+        const sourceAttr = t.jsxAttribute(
+          t.jsxIdentifier('data-keak-src'),
+          t.stringLiteral(sourceLocation)
+        );
+
+        // Add component context if available
+        let componentName = '';
+        let currentPath = nodePath;
+        
+        // Walk up to find the containing component
+        while (currentPath) {
+          if (currentPath.isFunctionDeclaration() && currentPath.node.id) {
+            componentName = currentPath.node.id.name;
+            break;
+          }
+          
+          if (currentPath.isVariableDeclarator() && t.isIdentifier(currentPath.node.id)) {
+            const init = currentPath.node.init;
+            if (t.isArrowFunctionExpression(init) || t.isFunctionExpression(init)) {
+              componentName = currentPath.node.id.name;
+              break;
+            }
+          }
+          
+          currentPath = currentPath.parentPath;
+        }
+
+        // Add component context attribute if found
+        if (componentName) {
+          const componentAttr = t.jsxAttribute(
+            t.jsxIdentifier('data-keak-component'),
+            t.stringLiteral(componentName)
+          );
+          nodePath.node.attributes.push(componentAttr);
+        }
+
+        // Add the source location attribute
+        nodePath.node.attributes.push(sourceAttr);
+        processedCount++;
+
+        // Optional: Add element index within component for disambiguation
+        if (state.opts.includeElementIndex) {
+          const elementIndex = state.elementIndex || 0;
+          state.elementIndex = elementIndex + 1;
+          
+          const indexAttr = t.jsxAttribute(
+            t.jsxIdentifier('data-keak-idx'),
+            t.stringLiteral(String(elementIndex))
+          );
+          nodePath.node.attributes.push(indexAttr);
+        }
+      }
+    }
+  };
+}
+
+module.exports = keakSourceInjectorPlugin;
+