@vodailoc/kilo-kit-mcp 1.1.0

package/skills/operations/chrome-devtools/scripts/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "chrome-devtools-scripts",
+  "version": "1.0.0",
+  "description": "Browser automation scripts for Chrome DevTools Agent Skill",
+  "type": "module",
+  "scripts": {},
+  "dependencies": {
+    "puppeteer": "^24.15.0",
+    "debug": "^4.4.0",
+    "yargs": "^17.7.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/skills/operations/chrome-devtools/scripts/performance.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+/**
+ * Measure performance metrics and record trace
+ * Usage: node performance.js --url https://example.com [--trace trace.json] [--metrics]
+ */
+import { getBrowser, getPage, closeBrowser, parseArgs, outputJSON, outputError } from './lib/browser.js';
+import fs from 'fs/promises';
+
+async function measurePerformance() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (!args.url) {
+    outputError(new Error('--url is required'));
+    return;
+  }
+
+  try {
+    const browser = await getBrowser({
+      headless: args.headless !== 'false'
+    });
+
+    const page = await getPage(browser);
+
+    // Start tracing if requested
+    if (args.trace) {
+      await page.tracing.start({
+        path: args.trace,
+        categories: [
+          'devtools.timeline',
+          'disabled-by-default-devtools.timeline',
+          'disabled-by-default-devtools.timeline.frame'
+        ]
+      });
+    }
+
+    // Navigate
+    await page.goto(args.url, {
+      waitUntil: 'networkidle2'
+    });
+
+    // Stop tracing
+    if (args.trace) {
+      await page.tracing.stop();
+    }
+
+    // Get performance metrics
+    const metrics = await page.metrics();
+
+    // Get Core Web Vitals
+    const vitals = await page.evaluate(() => {
+      return new Promise((resolve) => {
+        const vitals = {
+          LCP: null,
+          FID: null,
+          CLS: 0,
+          FCP: null,
+          TTFB: null
+        };
+
+        // LCP
+        try {
+          new PerformanceObserver((list) => {
+            const entries = list.getEntries();
+            if (entries.length > 0) {
+              const lastEntry = entries[entries.length - 1];
+              vitals.LCP = lastEntry.renderTime || lastEntry.loadTime;
+            }
+          }).observe({ entryTypes: ['largest-contentful-paint'], buffered: true });
+        } catch (e) {}
+
+        // CLS
+        try {
+          new PerformanceObserver((list) => {
+            list.getEntries().forEach((entry) => {
+              if (!entry.hadRecentInput) {
+                vitals.CLS += entry.value;
+              }
+            });
+          }).observe({ entryTypes: ['layout-shift'], buffered: true });
+        } catch (e) {}
+
+        // FCP
+        try {
+          const paintEntries = performance.getEntriesByType('paint');
+          const fcpEntry = paintEntries.find(e => e.name === 'first-contentful-paint');
+          if (fcpEntry) {
+            vitals.FCP = fcpEntry.startTime;
+          }
+        } catch (e) {}
+
+        // TTFB
+        try {
+          const [navigationEntry] = performance.getEntriesByType('navigation');
+          if (navigationEntry) {
+            vitals.TTFB = navigationEntry.responseStart - navigationEntry.requestStart;
+          }
+        } catch (e) {}
+
+        // Wait a bit for metrics to stabilize
+        setTimeout(() => resolve(vitals), 1000);
+      });
+    });
+
+    // Get resource timing
+    const resources = await page.evaluate(() => {
+      return performance.getEntriesByType('resource').map(r => ({
+        name: r.name,
+        type: r.initiatorType,
+        duration: r.duration,
+        size: r.transferSize,
+        startTime: r.startTime
+      }));
+    });
+
+    const result = {
+      success: true,
+      url: page.url(),
+      metrics: {
+        ...metrics,
+        JSHeapUsedSizeMB: (metrics.JSHeapUsedSize / 1024 / 1024).toFixed(2),
+        JSHeapTotalSizeMB: (metrics.JSHeapTotalSize / 1024 / 1024).toFixed(2)
+      },
+      vitals: vitals,
+      resources: {
+        count: resources.length,
+        totalDuration: resources.reduce((sum, r) => sum + r.duration, 0),
+        items: args.resources === 'true' ? resources : undefined
+      }
+    };
+
+    if (args.trace) {
+      result.trace = args.trace;
+    }
+
+    outputJSON(result);
+
+    if (args.close !== 'false') {
+      await closeBrowser();
+    }
+  } catch (error) {
+    outputError(error);
+  }
+}
+
+measurePerformance();

package/skills/operations/chrome-devtools/scripts/screenshot.js

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+/**
+ * Take a screenshot
+ * Usage: node screenshot.js --output screenshot.png [--url https://example.com] [--full-page true] [--selector .element] [--max-size 5] [--no-compress]
+ * Supports both CSS and XPath selectors:
+ *   - CSS: node screenshot.js --selector ".main-content" --output page.png
+ *   - XPath: node screenshot.js --selector "//div[@class='main-content']" --output page.png
+ */
+import { getBrowser, getPage, closeBrowser, parseArgs, outputJSON, outputError } from './lib/browser.js';
+import { parseSelector, getElement, enhanceError } from './lib/selector.js';
+import fs from 'fs/promises';
+import path from 'path';
+import { execSync } from 'child_process';
+
+/**
+ * Compress image using ImageMagick if it exceeds max size
+ * @param {string} filePath - Path to the image file
+ * @param {number} maxSizeMB - Maximum file size in MB (default: 5)
+ * @returns {Promise<{compressed: boolean, originalSize: number, finalSize: number}>}
+ */
+async function compressImageIfNeeded(filePath, maxSizeMB = 5) {
+  const stats = await fs.stat(filePath);
+  const originalSize = stats.size;
+  const maxSizeBytes = maxSizeMB * 1024 * 1024;
+
+  if (originalSize <= maxSizeBytes) {
+    return { compressed: false, originalSize, finalSize: originalSize };
+  }
+
+  try {
+    // Check if ImageMagick is available
+    try {
+      execSync('magick -version', { stdio: 'pipe' });
+    } catch {
+      try {
+        execSync('convert -version', { stdio: 'pipe' });
+      } catch {
+        console.error('Warning: ImageMagick not found. Install it to enable automatic compression.');
+        return { compressed: false, originalSize, finalSize: originalSize };
+      }
+    }
+
+    const ext = path.extname(filePath).toLowerCase();
+    const tempPath = filePath.replace(ext, `.temp${ext}`);
+
+    // Determine compression strategy based on file type
+    let compressionCmd;
+    if (ext === '.png') {
+      // For PNG: resize and compress with quality
+      compressionCmd = `magick "${filePath}" -strip -resize 90% -quality 85 "${tempPath}"`;
+    } else if (ext === '.jpg' || ext === '.jpeg') {
+      // For JPEG: compress with quality and progressive
+      compressionCmd = `magick "${filePath}" -strip -quality 80 -interlace Plane "${tempPath}"`;
+    } else {
+      // For other formats: convert to JPEG with compression
+      compressionCmd = `magick "${filePath}" -strip -quality 80 "${tempPath.replace(ext, '.jpg')}"`;
+    }
+
+    // Try compression
+    execSync(compressionCmd, { stdio: 'pipe' });
+
+    const compressedStats = await fs.stat(tempPath);
+    const compressedSize = compressedStats.size;
+
+    // If still too large, try more aggressive compression
+    if (compressedSize > maxSizeBytes) {
+      const finalPath = filePath.replace(ext, `.final${ext}`);
+      let aggressiveCmd;
+
+      if (ext === '.png') {
+        aggressiveCmd = `magick "${tempPath}" -strip -resize 75% -quality 70 "${finalPath}"`;
+      } else {
+        aggressiveCmd = `magick "${tempPath}" -strip -quality 60 -sampling-factor 4:2:0 "${finalPath}"`;
+      }
+
+      execSync(aggressiveCmd, { stdio: 'pipe' });
+      await fs.unlink(tempPath);
+      await fs.rename(finalPath, filePath);
+    } else {
+      await fs.rename(tempPath, filePath);
+    }
+
+    const finalStats = await fs.stat(filePath);
+    return { compressed: true, originalSize, finalSize: finalStats.size };
+  } catch (error) {
+    console.error('Compression error:', error.message);
+    // If compression fails, keep original file
+    try {
+      const tempPath = filePath.replace(path.extname(filePath), '.temp' + path.extname(filePath));
+      await fs.unlink(tempPath).catch(() => {});
+    } catch {}
+    return { compressed: false, originalSize, finalSize: originalSize };
+  }
+}
+
+async function screenshot() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (!args.output) {
+    outputError(new Error('--output is required'));
+    return;
+  }
+
+  try {
+    const browser = await getBrowser({
+      headless: args.headless !== 'false'
+    });
+
+    const page = await getPage(browser);
+
+    // Navigate if URL provided
+    if (args.url) {
+      await page.goto(args.url, {
+        waitUntil: args['wait-until'] || 'networkidle2'
+      });
+    }
+
+    const screenshotOptions = {
+      path: args.output,
+      type: args.format || 'png',
+      fullPage: args['full-page'] === 'true'
+    };
+
+    if (args.quality) {
+      screenshotOptions.quality = parseInt(args.quality);
+    }
+
+    let buffer;
+    if (args.selector) {
+      // Parse and validate selector
+      const parsed = parseSelector(args.selector);
+
+      // Get element based on selector type
+      const element = await getElement(page, parsed);
+      if (!element) {
+        throw new Error(`Element not found: ${args.selector}`);
+      }
+      buffer = await element.screenshot(screenshotOptions);
+    } else {
+      buffer = await page.screenshot(screenshotOptions);
+    }
+
+    const result = {
+      success: true,
+      output: path.resolve(args.output),
+      size: buffer.length,
+      url: page.url()
+    };
+
+    // Compress image if needed (unless --no-compress flag is set)
+    if (args['no-compress'] !== 'true') {
+      const maxSize = args['max-size'] ? parseFloat(args['max-size']) : 5;
+      const compressionResult = await compressImageIfNeeded(args.output, maxSize);
+
+      if (compressionResult.compressed) {
+        result.compressed = true;
+        result.originalSize = compressionResult.originalSize;
+        result.size = compressionResult.finalSize;
+        result.compressionRatio = ((1 - compressionResult.finalSize / compressionResult.originalSize) * 100).toFixed(2) + '%';
+      }
+    }
+
+    outputJSON(result);
+
+    if (args.close !== 'false') {
+      await closeBrowser();
+    }
+  } catch (error) {
+    // Enhance error message if selector-related
+    if (args.selector) {
+      const enhanced = enhanceError(error, args.selector);
+      outputError(enhanced);
+    } else {
+      outputError(error);
+    }
+    process.exit(1);
+  }
+}
+
+screenshot();

package/skills/operations/chrome-devtools/scripts/snapshot.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+/**
+ * Get DOM snapshot with selectors
+ * Usage: node snapshot.js [--url https://example.com] [--output snapshot.json]
+ */
+import { getBrowser, getPage, closeBrowser, parseArgs, outputJSON, outputError } from './lib/browser.js';
+import fs from 'fs/promises';
+
+async function snapshot() {
+  const args = parseArgs(process.argv.slice(2));
+
+  try {
+    const browser = await getBrowser({
+      headless: args.headless !== 'false'
+    });
+
+    const page = await getPage(browser);
+
+    // Navigate if URL provided
+    if (args.url) {
+      await page.goto(args.url, {
+        waitUntil: args['wait-until'] || 'networkidle2'
+      });
+    }
+
+    // Get interactive elements with metadata
+    const elements = await page.evaluate(() => {
+      const interactiveSelectors = [
+        'a[href]',
+        'button',
+        'input',
+        'textarea',
+        'select',
+        '[onclick]',
+        '[role="button"]',
+        '[role="link"]',
+        '[contenteditable]'
+      ];
+
+      const elements = [];
+      const selector = interactiveSelectors.join(', ');
+      const nodes = document.querySelectorAll(selector);
+
+      nodes.forEach((el, index) => {
+        const rect = el.getBoundingClientRect();
+
+        // Generate unique selector
+        let uniqueSelector = '';
+        if (el.id) {
+          uniqueSelector = `#${el.id}`;
+        } else if (el.className) {
+          const classes = Array.from(el.classList).join('.');
+          uniqueSelector = `${el.tagName.toLowerCase()}.${classes}`;
+        } else {
+          uniqueSelector = el.tagName.toLowerCase();
+        }
+
+        elements.push({
+          index: index,
+          tagName: el.tagName.toLowerCase(),
+          type: el.type || null,
+          id: el.id || null,
+          className: el.className || null,
+          name: el.name || null,
+          value: el.value || null,
+          text: el.textContent?.trim().substring(0, 100) || null,
+          href: el.href || null,
+          selector: uniqueSelector,
+          xpath: getXPath(el),
+          visible: rect.width > 0 && rect.height > 0,
+          position: {
+            x: rect.x,
+            y: rect.y,
+            width: rect.width,
+            height: rect.height
+          }
+        });
+      });
+
+      function getXPath(element) {
+        if (element.id) {
+          return `//*[@id="${element.id}"]`;
+        }
+        if (element === document.body) {
+          return '/html/body';
+        }
+        let ix = 0;
+        const siblings = element.parentNode?.childNodes || [];
+        for (let i = 0; i < siblings.length; i++) {
+          const sibling = siblings[i];
+          if (sibling === element) {
+            return getXPath(element.parentNode) + '/' + element.tagName.toLowerCase() + '[' + (ix + 1) + ']';
+          }
+          if (sibling.nodeType === 1 && sibling.tagName === element.tagName) {
+            ix++;
+          }
+        }
+        return '';
+      }
+
+      return elements;
+    });
+
+    const result = {
+      success: true,
+      url: page.url(),
+      title: await page.title(),
+      elementCount: elements.length,
+      elements: elements
+    };
+
+    if (args.output) {
+      await fs.writeFile(args.output, JSON.stringify(result, null, 2));
+      outputJSON({
+        success: true,
+        output: args.output,
+        elementCount: elements.length
+      });
+    } else {
+      outputJSON(result);
+    }
+
+    if (args.close !== 'false') {
+      await closeBrowser();
+    }
+  } catch (error) {
+    outputError(error);
+  }
+}
+
+snapshot();

package/skills/operations/deployment-procedures/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: deployment-procedures
+description: Production deployment principles and decision-making. Safe deployment workflows, rollback strategies, and verification. Teaches thinking, not scripts.
+allowed-tools: Read, Glob, Grep, Bash
+---
+
+# Deployment Procedures
+
+> Deployment principles and decision-making for safe production releases.
+> **Learn to THINK, not memorize scripts.**
+
+---
+
+## ⚠️ How to Use This Skill
+
+This skill teaches **deployment principles**, not bash scripts to copy.
+
+- Every deployment is unique
+- Understand the WHY behind each step
+- Adapt procedures to your platform
+
+---
+
+## 1. Platform Selection
+
+### Decision Tree
+
+```
+What are you deploying?
+│
+├── Static site / JAMstack
+│   └── Vercel, Netlify, Cloudflare Pages
+│
+├── Simple web app
+│   ├── Managed → Railway, Render, Fly.io
+│   └── Control → VPS + PM2/Docker
+│
+├── Microservices
+│   └── Container orchestration
+│
+└── Serverless
+    └── Edge functions, Lambda
+```
+
+### Each Platform Has Different Procedures
+
+| Platform | Deployment Method |
+|----------|------------------|
+| **Vercel/Netlify** | Git push, auto-deploy |
+| **Railway/Render** | Git push or CLI |
+| **VPS + PM2** | SSH + manual steps |
+| **Docker** | Image push + orchestration |
+| **Kubernetes** | kubectl apply |
+
+---
+
+## 2. Pre-Deployment Principles
+
+### The 4 Verification Categories
+
+| Category | What to Check |
+|----------|--------------|
+| **Code Quality** | Tests passing, linting clean, reviewed |
+| **Build** | Production build works, no warnings |
+| **Environment** | Env vars set, secrets current |
+| **Safety** | Backup done, rollback plan ready |
+
+### Pre-Deployment Checklist
+
+- [ ] All tests passing
+- [ ] Code reviewed and approved
+- [ ] Production build successful
+- [ ] Environment variables verified
+- [ ] Database migrations ready (if any)
+- [ ] Rollback plan documented
+- [ ] Team notified
+- [ ] Monitoring ready
+
+---
+
+## 3. Deployment Workflow Principles
+
+### The 5-Phase Process
+
+```
+1. PREPARE
+   └── Verify code, build, env vars
+
+2. BACKUP
+   └── Save current state before changing
+
+3. DEPLOY
+   └── Execute with monitoring open
+
+4. VERIFY
+   └── Health check, logs, key flows
+
+5. CONFIRM or ROLLBACK
+   └── All good? Confirm. Issues? Rollback.
+```
+
+### Phase Principles
+
+| Phase | Principle |
+|-------|-----------|
+| **Prepare** | Never deploy untested code |
+| **Backup** | Can't rollback without backup |
+| **Deploy** | Watch it happen, don't walk away |
+| **Verify** | Trust but verify |
+| **Confirm** | Have rollback trigger ready |
+
+---
+
+## 4. Post-Deployment Verification
+
+### What to Verify
+
+| Check | Why |
+|-------|-----|
+| **Health endpoint** | Service is running |
+| **Error logs** | No new errors |
+| **Key user flows** | Critical features work |
+| **Performance** | Response times acceptable |
+
+### Verification Window
+
+- **First 5 minutes**: Active monitoring
+- **15 minutes**: Confirm stable
+- **1 hour**: Final verification
+- **Next day**: Review metrics
+
+---
+
+## 5. Rollback Principles
+
+### When to Rollback
+
+| Symptom | Action |
+|---------|--------|
+| Service down | Rollback immediately |
+| Critical errors | Rollback |
+| Performance >50% degraded | Consider rollback |
+| Minor issues | Fix forward if quick |
+
+### Rollback Strategy by Platform
+
+| Platform | Rollback Method |
+|----------|----------------|
+| **Vercel/Netlify** | Redeploy previous commit |
+| **Railway/Render** | Rollback in dashboard |
+| **VPS + PM2** | Restore backup, restart |
+| **Docker** | Previous image tag |
+| **K8s** | kubectl rollout undo |
+
+### Rollback Principles
+
+1. **Speed over perfection**: Rollback first, debug later
+2. **Don't compound errors**: One rollback, not multiple changes
+3. **Communicate**: Tell team what happened
+4. **Post-mortem**: Understand why after stable
+
+---
+
+## 6. Zero-Downtime Deployment
+
+### Strategies
+
+| Strategy | How It Works |
+|----------|--------------|
+| **Rolling** | Replace instances one by one |
+| **Blue-Green** | Switch traffic between environments |
+| **Canary** | Gradual traffic shift |
+
+### Selection Principles
+
+| Scenario | Strategy |
+|----------|----------|
+| Standard release | Rolling |
+| High-risk change | Blue-green (easy rollback) |
+| Need validation | Canary (test with real traffic) |
+
+---
+
+## 7. Emergency Procedures
+
+### Service Down Priority
+
+1. **Assess**: What's the symptom?
+2. **Quick fix**: Restart if unclear
+3. **Rollback**: If restart doesn't help
+4. **Investigate**: After stable
+
+### Investigation Order
+
+| Check | Common Issues |
+|-------|--------------|
+| **Logs** | Errors, exceptions |
+| **Resources** | Disk full, memory |
+| **Network** | DNS, firewall |
+| **Dependencies** | Database, APIs |
+
+---
+
+## 8. Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Deploy on Friday | Deploy early in week |
+| Rush deployment | Follow the process |
+| Skip staging | Always test first |
+| Deploy without backup | Backup before deploy |
+| Walk away after deploy | Monitor for 15+ min |
+| Multiple changes at once | One change at a time |
+
+---
+
+## 9. Decision Checklist
+
+Before deploying:
+
+- [ ] **Platform-appropriate procedure?**
+- [ ] **Backup strategy ready?**
+- [ ] **Rollback plan documented?**
+- [ ] **Monitoring configured?**
+- [ ] **Team notified?**
+- [ ] **Time to monitor after?**
+
+---
+
+## 10. Best Practices
+
+1. **Small, frequent deploys** over big releases
+2. **Feature flags** for risky changes
+3. **Automate** repetitive steps
+4. **Document** every deployment
+5. **Review** what went wrong after issues
+6. **Test rollback** before you need it
+
+---
+
+> **Remember:** Every deployment is a risk. Minimize risk through preparation, not speed.