myaidev-method 0.3.3 → 0.3.5

package/skills/myaidev-figma/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: myaidev-figma
+description: Capture any website (all pages or selected sub-pages) and push the designs directly into a Figma file. Invoke this when the user wants to import, capture, screenshot, or convert a website into Figma designs.
+user-invocable: true
+allowed-tools: Bash, Read, Write, Edit, mcp__figma-remote-mcp__generate_figma_design
+---
+
+# /myaidev-figma — Website → Figma Design Capture
+
+You are now running the **myaidev-figma** skill. Your job is to capture a live website (homepage + sub-pages) and push every selected page into a Figma file as a pixel-faithful design. Follow every step precisely.
+
+---
+
+## STEP 0 — Greet & Collect Inputs
+
+Tell the user:
+> "**myaidev-figma** — Website to Figma Capture
+> I'll crawl your site, let you pick which pages to capture, and push them all into Figma."
+
+Then ask these three questions **together in one message**:
+
+1. **Website URL** — what is the root URL to capture? (e.g. `https://example.com`)
+2. **Figma destination** — should I:
+   - (a) Create a **new** Figma file — if so, what should it be named?
+   - (b) Add to an **existing** Figma file — if so, paste the Figma file URL or key.
+3. **Crawl depth** — how deep should I go finding sub-pages? (`1` = direct links from homepage, `2` = two levels deep). Default is `1`.
+
+Wait for the user's answers before continuing.
+
+---
+
+## STEP 1 — Ensure Playwright is Available
+
+Run this shell check:
+
+```bash
+npx playwright --version 2>/dev/null || echo "NOT_INSTALLED"
+```
+
+**If playwright is missing** (output contains `NOT_INSTALLED`):
+- Tell the user: "Installing Playwright MCP server and browser dependencies — this may take a minute..."
+- Run: `npm install -g @playwright/mcp playwright 2>&1 | tail -5`
+- Then install the Chromium browser: `npx playwright install chromium 2>&1 | tail -10`
+- After install, verify: `npx playwright --version`
+
+**Also ensure the Playwright MCP server is registered with Claude:**
+```bash
+claude mcp get playwright 2>/dev/null || claude mcp add playwright -- npx @playwright/mcp 2>&1
+```
+
+If the `mcp add` succeeded, tell the user:
+> "Playwright MCP server registered. **Please restart Claude Code** once to activate MCP, then run `/myaidev-figma` again."
+> Then **stop** — do not continue until the user restarts.
+
+If playwright was already installed and the MCP was already registered, continue to STEP 2.
+
+---
+
+## STEP 2 — Find the Playwright + Chromium Paths
+
+Run these to discover the environment:
+
+```bash
+# Find playwright package
+PLAYWRIGHT_PKG=$(find ~/.npm/_npx -name "playwright" -type d -maxdepth 8 2>/dev/null | sort -r | head -1)
+echo "PLAYWRIGHT_PKG=$PLAYWRIGHT_PKG"
+
+# Find Chromium executable (macOS)
+CHROMIUM=$(find ~/Library/Caches/ms-playwright -name "chrome-headless-shell" -o -name "Chromium" -type f 2>/dev/null | grep -v ".pak" | sort -r | head -1)
+# Try Linux if macOS yields nothing
+if [ -z "$CHROMIUM" ]; then
+  CHROMIUM=$(find ~/.cache/ms-playwright -name "chrome" -type f 2>/dev/null | sort -r | head -1)
+fi
+echo "CHROMIUM=$CHROMIUM"
+```
+
+Save these values — you will use them in the Node.js scripts below. If `PLAYWRIGHT_PKG` is empty, the package may be installed globally; try:
+```bash
+PLAYWRIGHT_PKG=$(node -e "console.log(require.resolve('playwright').replace('/index.js',''))" 2>/dev/null || echo "")
+```
+
+---
+
+## STEP 3 — Crawl the Website to Discover Pages
+
+Use the crawl.js script located at `~/.claude/skills/myaidev-figma/crawl.js`.
+
+Run it like this (replace paths with what you found in STEP 2):
+```bash
+NODE_PATH="<PLAYWRIGHT_PKG>/.." node ~/.claude/skills/myaidev-figma/crawl.js "<USER_URL>" <CRAWL_DEPTH> 2>/tmp/dev-f-crawl-err.log
+```
+
+If crawl.js fails (bad NODE_PATH, etc.), fall back to using `mcp__playwright__browser_navigate` to navigate to the URL and extract links from the page snapshot. Extract all `<a href>` links that share the same origin as the root URL.
+
+Parse the JSON output. You now have a list of pages like:
+```json
+[
+  { "url": "https://example.com/", "title": "Home", "depth": 0 },
+  { "url": "https://example.com/pricing", "title": "Pricing", "depth": 1 },
+  ...
+]
+```
+
+**Present the discovered pages to the user** in a numbered list:
+```
+Found N pages:
+  1. / — Home
+  2. /pricing — Pricing
+  3. /about — About Us
+  ...
+
+Which pages would you like to capture?
+Enter numbers (e.g. "1 3 5"), "all", or "1-5" for a range.
+(Tip: capturing many pages takes longer — start with a few to test)
+```
+
+Wait for the user's selection. Parse it into the final list of URLs to capture.
+
+---
+
+## STEP 4 — Set Up Figma Destination
+
+Call `mcp__figma-remote-mcp__generate_figma_design` **without any parameters** first to get the current options/plans list.
+
+Based on the user's answer from STEP 0:
+
+**If new file:**
+- Use `outputMode: "newFile"` with the user's chosen `fileName` and the appropriate `planKey` from the options list.
+
+**If existing file:**
+- Extract `fileKey` from the URL they pasted (format: `figma.com/design/<fileKey>/...`).
+- Use `outputMode: "existingFile"` with that `fileKey`.
+
+Generate **one capture ID per page** by calling `mcp__figma-remote-mcp__generate_figma_design` with the chosen outputMode once per page. Store each `captureId` and `endpoint` from the responses.
+
+> Important: call generate_figma_design once per page to get separate captureIds. For `existingFile`, use the same `fileKey` for all calls.
+
+---
+
+## STEP 5 — Capture Each Page
+
+For each page in the user's selection, run `capture.js`:
+
+```bash
+NODE_PATH="<PLAYWRIGHT_PKG>/.." node ~/.claude/skills/myaidev-figma/capture.js \
+  "<PAGE_URL>" \
+  "<CAPTURE_ID>" \
+  "<ENDPOINT_URL>" \
+  "body" \
+  2>/tmp/dev-f-capture-<slug>.log
+```
+
+**Run captures sequentially** (one at a time) to avoid overloading the browser.
+
+After each capture starts, immediately begin polling:
+
+```
+Poll loop (up to 10 times, every 5 seconds):
+  Call mcp__figma-remote-mcp__generate_figma_design with captureId: "<CAPTURE_ID>"
+  If status == "completed" → move to next page
+  If status == "pending" or "processing" → wait 5s and retry
+  If still pending after 10 polls → log error and move on
+```
+
+Show the user a live status line per page:
+```
+[1/5] Capturing https://example.com/ ... ✓ Done
+[2/5] Capturing https://example.com/pricing ... ⏳ Processing...
+```
+
+---
+
+## STEP 6 — Report Results
+
+Once all captures are done, tell the user:
+
+```
+✓ myaidev-figma complete! X of Y pages captured.
+
+Figma file: <FIGMA_FILE_URL>
+
+Pages captured:
+  ✓ / — Home
+  ✓ /pricing — Pricing
+  ✗ /blog — Failed (timeout)
+
+To capture more pages or re-capture a page, just run /myaidev-figma again.
+The Figma capture toolbar (visible in the browser) also lets you manually re-capture pages at any time.
+```
+
+Open the Figma file:
+```bash
+open "<FIGMA_FILE_URL>"
+```
+
+---
+
+## Error Handling
+
+- **Capture returns `success: false`**: The captureId may have expired. Generate a new one and retry that page once.
+- **Node.js script not found**: Use the absolute path `~/.claude/skills/myaidev-figma/capture.js`.
+- **`window.figma` not defined after injection**: The CSP stripping may have failed. Try navigating to the page with hash params approach or report the issue to the user.
+- **Browser not found**: Run `npx playwright install chromium` and retry.
+- **Rate limits or network errors**: Wait 10 seconds and retry up to 3 times.
+
+---
+
+## Notes
+
+- The `$ARGUMENTS` variable contains anything the user typed after `/myaidev-figma`. If they passed a URL directly (e.g. `/myaidev-figma https://example.com`), skip asking for the URL in STEP 0 and use `$ARGUMENTS` as the URL.
+- Always be transparent about what you're doing — show the Bash commands you run and their outputs.
+- If the user already has Playwright MCP tools available (`mcp__playwright__browser_navigate` etc.), prefer using those for navigation in STEP 3 instead of the Node.js crawl script.

package/skills/myaidev-figma/capture.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/**
+ * dev-f capture script
+ * Usage: node capture.js <url> <captureId> <endpoint> [selector]
+ * Captures a webpage and submits it to the Figma MCP capture endpoint.
+ */
+
+const { chromium } = require('playwright');
+
+const [,, targetUrl, captureId, endpoint, selector = 'body'] = process.argv;
+
+if (!targetUrl || !captureId || !endpoint) {
+  console.error('Usage: node capture.js <url> <captureId> <endpoint> [selector]');
+  process.exit(1);
+}
+
+// Find an available Chromium executable
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+function findChromium() {
+  const base = path.join(os.homedir(), 'Library', 'Caches', 'ms-playwright');
+  if (!fs.existsSync(base)) return null;
+
+  const dirs = fs.readdirSync(base)
+    .filter(d => d.startsWith('chromium'))
+    .sort()
+    .reverse(); // prefer newer
+
+  for (const dir of dirs) {
+    // arm64
+    const arm = path.join(base, dir, 'chrome-mac-arm64', 'Chromium.app', 'Contents', 'MacOS', 'Chromium');
+    if (fs.existsSync(arm)) return arm;
+    // headless shell arm64
+    const shell_arm = path.join(base, dir, 'chrome-headless-shell-mac-arm64', 'chrome-headless-shell');
+    if (fs.existsSync(shell_arm)) return shell_arm;
+    // x64
+    const x64 = path.join(base, dir, 'chrome-mac-x64', 'Chromium.app', 'Contents', 'MacOS', 'Chromium');
+    if (fs.existsSync(x64)) return x64;
+    const shell_x64 = path.join(base, dir, 'chrome-headless-shell-mac-x64', 'chrome-headless-shell');
+    if (fs.existsSync(shell_x64)) return shell_x64;
+  }
+
+  // Linux paths
+  const linuxBase = path.join(os.homedir(), '.cache', 'ms-playwright');
+  if (fs.existsSync(linuxBase)) {
+    const ldirs = fs.readdirSync(linuxBase).filter(d => d.startsWith('chromium')).sort().reverse();
+    for (const dir of ldirs) {
+      const lp = path.join(linuxBase, dir, 'chrome-linux', 'chrome');
+      if (fs.existsSync(lp)) return lp;
+      const ls = path.join(linuxBase, dir, 'chrome-linux', 'chrome-headless-shell');
+      if (fs.existsSync(ls)) return ls;
+    }
+  }
+
+  return null;
+}
+
+(async () => {
+  const executablePath = findChromium();
+
+  const launchOptions = { headless: true };
+  if (executablePath) {
+    launchOptions.executablePath = executablePath;
+    process.stderr.write(`Using Chromium: ${executablePath}\n`);
+  } else {
+    process.stderr.write('No cached Chromium found, using Playwright default (may need install)\n');
+  }
+
+  const browser = await chromium.launch(launchOptions);
+  const context = await browser.newContext({ viewport: { width: 1440, height: 900 } });
+  const page = await context.newPage();
+
+  // Strip CSP headers so the injected capture script can run
+  await page.route('**/*', async (route) => {
+    try {
+      const response = await route.fetch();
+      const headers = { ...response.headers() };
+      delete headers['content-security-policy'];
+      delete headers['content-security-policy-report-only'];
+      await route.fulfill({ response, headers });
+    } catch (e) {
+      await route.continue();
+    }
+  });
+
+  process.stderr.write(`Navigating to: ${targetUrl}\n`);
+  await page.goto(targetUrl, { waitUntil: 'load', timeout: 60000 });
+  await page.waitForTimeout(2000);
+  process.stderr.write(`Title: ${await page.title()}\n`);
+
+  // Fetch and inject the Figma capture script
+  const r = await context.request.get('https://mcp.figma.com/mcp/html-to-design/capture.js');
+  const scriptText = await r.text();
+  process.stderr.write(`Capture script fetched (${scriptText.length} bytes)\n`);
+
+  await page.evaluate((s) => {
+    const el = document.createElement('script');
+    el.textContent = s;
+    document.head.appendChild(el);
+  }, scriptText);
+
+  await page.waitForTimeout(1000);
+
+  const hasFigma = await page.evaluate(() => typeof window.figma !== 'undefined');
+  if (!hasFigma) {
+    process.stderr.write('ERROR: window.figma not available after script injection\n');
+    await browser.close();
+    process.exit(1);
+  }
+
+  process.stderr.write('Submitting capture...\n');
+  const result = await page.evaluate(
+    async ({ captureId, endpoint, selector }) => {
+      return await window.figma.captureForDesign({ captureId, endpoint, selector });
+    },
+    { captureId, endpoint, selector }
+  );
+
+  process.stderr.write(`Result: ${JSON.stringify(result)}\n`);
+  await browser.close();
+
+  if (result && result.success === false) {
+    process.stderr.write(`Capture failed: ${result.error}\n`);
+    process.exit(1);
+  }
+
+  console.log(JSON.stringify(result));
+})().catch(e => {
+  process.stderr.write(`Fatal: ${e.message}\n`);
+  process.exit(1);
+});

package/skills/myaidev-figma/crawl.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+/**
+ * dev-f crawl script
+ * Usage: node crawl.js <url> [maxDepth]
+ * Crawls a website and outputs a JSON array of discovered internal page URLs.
+ */
+
+const { chromium } = require('playwright');
+
+const [,, rootUrl, maxDepthArg = '1'] = process.argv;
+const maxDepth = parseInt(maxDepthArg, 10);
+
+if (!rootUrl) {
+  console.error('Usage: node crawl.js <url> [maxDepth]');
+  process.exit(1);
+}
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+function findChromium() {
+  const base = path.join(os.homedir(), 'Library', 'Caches', 'ms-playwright');
+  if (!fs.existsSync(base)) return null;
+  const dirs = fs.readdirSync(base).filter(d => d.startsWith('chromium')).sort().reverse();
+  for (const dir of dirs) {
+    const shell_arm = path.join(base, dir, 'chrome-headless-shell-mac-arm64', 'chrome-headless-shell');
+    if (fs.existsSync(shell_arm)) return shell_arm;
+    const arm = path.join(base, dir, 'chrome-mac-arm64', 'Chromium.app', 'Contents', 'MacOS', 'Chromium');
+    if (fs.existsSync(arm)) return arm;
+    const x64 = path.join(base, dir, 'chrome-mac-x64', 'Chromium.app', 'Contents', 'MacOS', 'Chromium');
+    if (fs.existsSync(x64)) return x64;
+    const shell_x64 = path.join(base, dir, 'chrome-headless-shell-mac-x64', 'chrome-headless-shell');
+    if (fs.existsSync(shell_x64)) return shell_x64;
+  }
+  const linuxBase = path.join(os.homedir(), '.cache', 'ms-playwright');
+  if (fs.existsSync(linuxBase)) {
+    const ldirs = fs.readdirSync(linuxBase).filter(d => d.startsWith('chromium')).sort().reverse();
+    for (const dir of ldirs) {
+      const lp = path.join(linuxBase, dir, 'chrome-linux', 'chrome');
+      if (fs.existsSync(lp)) return lp;
+    }
+  }
+  return null;
+}
+
+function normalizeUrl(href, base) {
+  try {
+    const u = new URL(href, base);
+    u.hash = '';
+    if (u.pathname !== '/' && u.pathname.endsWith('/')) {
+      u.pathname = u.pathname.slice(0, -1);
+    }
+    return u.toString();
+  } catch {
+    return null;
+  }
+}
+
+(async () => {
+  const rootParsed = new URL(rootUrl);
+  const origin = rootParsed.origin;
+
+  const executablePath = findChromium();
+  const launchOptions = { headless: true };
+  if (executablePath) launchOptions.executablePath = executablePath;
+
+  const browser = await chromium.launch(launchOptions);
+  const context = await browser.newContext({ viewport: { width: 1440, height: 900 } });
+
+  const visited = new Set();
+  const queue = [{ url: normalizeUrl(rootUrl, rootUrl), depth: 0 }];
+  const pages = [];
+
+  // Always include the root
+  const rootNorm = normalizeUrl(rootUrl, rootUrl);
+  visited.add(rootNorm);
+  pages.push({ url: rootNorm, title: '', depth: 0 });
+
+  while (queue.length > 0) {
+    const { url, depth } = queue.shift();
+    if (depth > maxDepth) continue;
+
+    process.stderr.write(`Crawling (depth ${depth}): ${url}\n`);
+    const page = await context.newPage();
+
+    try {
+      await page.goto(url, { waitUntil: 'load', timeout: 30000 });
+      await page.waitForTimeout(500);
+
+      // Update title for this page
+      const title = await page.title();
+      const existing = pages.find(p => p.url === url);
+      if (existing) existing.title = title;
+
+      if (depth < maxDepth) {
+        // Extract all internal links
+        const links = await page.evaluate((origin) => {
+          return Array.from(document.querySelectorAll('a[href]'))
+            .map(a => a.href)
+            .filter(h => h.startsWith(origin));
+        }, origin);
+
+        for (const link of links) {
+          const norm = normalizeUrl(link, url);
+          if (!norm) continue;
+          if (!norm.startsWith(origin)) continue;
+          // Skip non-page URLs
+          if (/\.(pdf|zip|png|jpg|jpeg|gif|svg|ico|css|js|xml|json|woff|woff2|ttf|eot)(\?|$)/i.test(norm)) continue;
+          if (!visited.has(norm)) {
+            visited.add(norm);
+            const pg = { url: norm, title: '', depth: depth + 1 };
+            pages.push(pg);
+            queue.push({ url: norm, depth: depth + 1 });
+          }
+        }
+      }
+    } catch (e) {
+      process.stderr.write(`Failed to crawl ${url}: ${e.message}\n`);
+    } finally {
+      await page.close();
+    }
+  }
+
+  await browser.close();
+  console.log(JSON.stringify(pages, null, 2));
+})().catch(e => {
+  process.stderr.write(`Fatal: ${e.message}\n`);
+  process.exit(1);
+});

package/skills/myaidev-figma-configure/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: myaidev-figma-configure
+description: One-time setup for myaidev-figma. Registers Playwright MCP and Figma Remote MCP, installs the Figma plugin, and walks the user through Figma authentication. Run this before using /myaidev-figma for the first time.
+user-invocable: true
+allowed-tools: Bash, mcp__figma-remote-mcp__whoami
+---
+
+# /myaidev-figma-configure — One-time Setup
+
+You are running **myaidev-figma-configure**. Your job is to get the user's environment ready for `/myaidev-figma` in as few steps as possible.
+
+Greet the user:
+
+> "**myaidev-figma-configure** — One-time Setup
+> I'll register Playwright MCP, Figma Remote MCP, install the Figma plugin, and verify your Figma authentication. This only needs to be done once."
+
+Track two flags as you proceed:
+- `NEEDS_RESTART` — set to true if any MCP was newly registered
+- `AUTH_NEEDED` — set to true if Figma authentication still needs to happen
+
+---
+
+## STEP 1 — Register Playwright MCP
+
+Check if already registered:
+```bash
+claude mcp get playwright 2>/dev/null && echo "ALREADY_REGISTERED" || echo "NOT_REGISTERED"
+```
+
+**If NOT_REGISTERED:**
+```bash
+claude mcp add playwright -- npx @playwright/mcp 2>&1
+```
+- On success: tell user "✓ Playwright MCP registered." Set `NEEDS_RESTART=true`.
+- On failure: tell user the exact error and stop — they may need to update Claude Code (`npm install -g @anthropic-ai/claude-code`).
+
+**If ALREADY_REGISTERED:**
+- Tell user: "✓ Playwright MCP already registered."
+
+---
+
+## STEP 2 — Register Figma Remote MCP
+
+```bash
+claude mcp get figma-remote-mcp 2>/dev/null && echo "ALREADY_REGISTERED" || echo "NOT_REGISTERED"
+```
+
+**If NOT_REGISTERED:**
+```bash
+claude mcp add --transport http figma-remote-mcp https://mcp.figma.com/mcp 2>&1
+```
+- On success: tell user "✓ Figma Remote MCP registered." Set `NEEDS_RESTART=true`.
+- On failure: tell user the exact error and stop.
+
+**If ALREADY_REGISTERED:**
+- Tell user: "✓ Figma Remote MCP already registered."
+
+---
+
+## STEP 3 — Install Figma Plugin
+
+```bash
+claude plugin install figma@claude-plugin-directory 2>&1
+echo "EXIT:$?"
+```
+
+- If exit code is 0: tell user "✓ Figma plugin installed."
+- If exit code is non-zero or command not found: tell the user:
+  > "After restarting, run this slash command to install the Figma plugin: `/plugin install figma@claude-plugin-directory`"
+
+---
+
+## STEP 4 — Authenticate with Figma
+
+**If `NEEDS_RESTART=true`:** Skip this step. Jump to STEP 5.
+
+**If everything was already registered (no restart needed):**
+
+Tell user: "Verifying your Figma authentication..."
+
+Call `mcp__figma-remote-mcp__whoami`.
+
+**Case A — returns user details (name/email):**
+- Tell user: "✓ Authenticated with Figma as **[name]**."
+- No further action needed.
+
+**Case B — returns an auth URL or login prompt:**
+- Open it automatically:
+  ```bash
+  open "<AUTH_URL>"
+  ```
+- Tell user:
+  > "A Figma login page has opened in your browser. Sign in and authorize access, then let me know when done."
+- Wait for user confirmation.
+- Call `mcp__figma-remote-mcp__whoami` again.
+  - If user details returned: "✓ Authenticated as **[name]**. All done!"
+  - If still failing: tell user to try opening the URL manually or re-run `/myaidev-figma-configure`.
+
+---
+
+## STEP 5 — Summary
+
+**If `NEEDS_RESTART=true`:**
+
+Print:
+```
+✓ Setup complete!
+
+  ✓ Playwright MCP — registered
+  ✓ Figma Remote MCP — registered
+  ✓ Figma plugin — installed
+
+Next steps:
+  1. Restart Claude Code  ← MCPs only activate after a restart
+  2. Run /myaidev-figma-configure again to complete Figma authentication
+  3. Then run /myaidev-figma to start capturing
+```
+
+**If everything was already set up and authentication passed:**
+
+Print:
+```
+✓ All set!
+
+  ✓ Playwright MCP — ready
+  ✓ Figma Remote MCP — ready
+  ✓ Figma — authenticated as [name]
+
+Run /myaidev-figma to start capturing websites into Figma.
+```