@pedroab0/skills 1.0.0 → 1.1.0

package/figma-to-code/SKILL.md

@@ -17,7 +17,7 @@ This skill connects to the Figma REST API, extracts a compact design-system-awar
 > **NEVER use browser tools (Playwright, Puppeteer, Chrome DevTools, `browser_navigate`, `read_browser_page`) on Figma URLs.**
 >
 > 1. **Figma Canvas is WebGL/Wasm**: Figma renders design canvas elements inside an HTML5 `<canvas>` via WebAssembly. There are NO inspectable HTML DOM elements for frames, layers, texts, or styles. Browser automation cannot extract Figma nodes or properties.
-> 2. **Never search `/Applications` for browsers**: Do not search for installed browser binaries or run browser automation scripts.
+> 2. **Never search for local browser binaries**: Do not search OS application directories (e.g., `/Applications`, `Program Files`, `/usr/bin`) or run browser automation scripts.
 > 3. **API Errors Are Final**: If `fetch_figma.js` returns an API error (e.g., 401 Unauthorized, 403 Forbidden, or 429 Rate Limited), **report the error directly to the user**. Guide them to check their `FIGMA_ACCESS_TOKEN`, permissions, or wait out rate limits. Do NOT attempt browser scraping fallbacks.
 
 ---
@@ -27,7 +27,7 @@ This skill connects to the Figma REST API, extracts a compact design-system-awar
 To protect your Figma file quota and prevent lockout penalties, `fetch_figma.js` enforces an automatic safety gate:
 * **Max 5 requests per minute** per file key (sliding window limit).
 * **2.5s inter-request pacing** between consecutive requests.
-* **Persistent Circuit Breaker**: If Figma returns HTTP 429, the script records the lockout time locally in `~/.figma_ratelimit.json`. All future calls to that file key are **immediately blocked with zero network traffic**, preventing Figma from extending the lockout penalty.
+* **Persistent Circuit Breaker**: If Figma returns HTTP 429, the script records the lockout time locally in `.figma_ratelimit.json` inside the user's home directory. All future calls to that file key are **immediately blocked with zero network traffic**, preventing Figma from extending the lockout penalty.
 
 ### Agent Behavioral Rules (Zero-Hammer Protocol)
 1. **Single-Shot Execution**: Run `fetch_figma.js` **once** per target frame or component.
@@ -41,7 +41,9 @@ To protect your Figma file quota and prevent lockout penalties, `fetch_figma.js`
 A Figma Access Token (Personal Access Token or OAuth Token) is required.
 
 Configure it using either:
-1. **Environment Variable**: `export FIGMA_ACCESS_TOKEN="figd_your_token_here"` or `export FIGMA_TOKEN="..."`
+1. **Environment Variable**:
+   - **macOS / Linux**: `export FIGMA_ACCESS_TOKEN="figd_your_token_here"` (or `FIGMA_TOKEN`)
+   - **Windows (PowerShell)**: `[Environment]::SetEnvironmentVariable("FIGMA_ACCESS_TOKEN", "figd_your_token_here", "User")` or `$env:FIGMA_ACCESS_TOKEN="figd_your_token_here"` in `$PROFILE`
 2. **Workspace `.env` File**:
    ```env
    FIGMA_ACCESS_TOKEN=figd_your_token_here
@@ -66,20 +68,20 @@ FIGMA_IGNORE_SSL=true
 
 ## Agent Execution Instructions
 
-To extract and build UI from a Figma URL, run `fetch_figma.js` from the skill's scripts directory:
+To extract and build UI from a Figma URL, run `fetch_figma.js` from this skill's `scripts/` directory:
 
 ```bash
 # Recommended: Extract compact AST (1 Tier 1 call)
-node <skill-dir>/scripts/fetch_figma.js "<FigmaURL>"
+node "<skill-dir>/scripts/fetch_figma.js" "<FigmaURL>"
 
 # Optional: With companion preview image (2 Tier 1 calls)
-node <skill-dir>/scripts/fetch_figma.js "<FigmaURL>" -i
+node "<skill-dir>/scripts/fetch_figma.js" "<FigmaURL>" -i
 ```
 
-**Script Path Resolution**:
-- **Global Antigravity install**: `node ~/.gemini/config/skills/figma-to-code/scripts/fetch_figma.js "<FigmaURL>"`
-- **Global Claude Code install**: `node ~/.claude/skills/figma-to-code/scripts/fetch_figma.js "<FigmaURL>"`
-- **Project local install**: `node figma-to-code/scripts/fetch_figma.js "<FigmaURL>"`
+**Resolving `<skill-dir>` (Agent-Agnostic)**:
+Substitute `<skill-dir>` with the directory where this skill is installed — **never guess another agent's folder** (always keep double quotes around the script path for Windows/macOS/Linux compatibility):
+- **Standard Skills (`SKILL.md`)**: `<skill-dir>` is the exact parent directory of this `SKILL.md` file.
+- **Cursor Rule (`.cursor/rules/figma-to-code.mdc`)**: `<skill-dir>` is the sibling `.cursor/skills/figma-to-code` directory (replace `rules/figma-to-code.mdc` with `skills/figma-to-code`).
 
 ---
 
@@ -89,13 +91,13 @@ node <skill-dir>/scripts/fetch_figma.js "<FigmaURL>" -i
 
 ```bash
 # Standard extraction (1 Tier 1 call - recommended)
-node figma-to-code/scripts/fetch_figma.js "https://www.figma.com/design/:fileKey/:name?node-id=4023-474"
+node "<skill-dir>/scripts/fetch_figma.js" "https://www.figma.com/design/:fileKey/:name?node-id=4023-474"
 
 # Optional: With preview image (2 Tier 1 calls)
-node figma-to-code/scripts/fetch_figma.js "https://www.figma.com/design/:fileKey/:name?node-id=4023-474" -i
+node "<skill-dir>/scripts/fetch_figma.js" "https://www.figma.com/design/:fileKey/:name?node-id=4023-474" -i
 
 # Collapse internal layers of component instances into props (guides agent to reuse existing components)
-node figma-to-code/scripts/fetch_figma.js "https://www.figma.com/design/:fileKey/:name?node-id=4023-474" --shallow-instances
+node "<skill-dir>/scripts/fetch_figma.js" "https://www.figma.com/design/:fileKey/:name?node-id=4023-474" --shallow-instances
 ```
 
 ### 2. CLI Flags Reference
@@ -169,7 +171,7 @@ When an `INSTANCE` node is present, internal property hashes are converted into
 
 ## How to Build Components from the Extracted Data
 
-When synthesizing code from the output:
+When synthesizing code from the output (always adapting syntax, attributes, and styling conventions to the project's detected stack — e.g., React, Vue, Svelte, Angular, or plain HTML/CSS):
 
 1. **Using Existing UI Components**:
    - For `INSTANCE` nodes with resolved `component.name` and `props`:
@@ -202,10 +204,10 @@ When synthesizing code from the output:
 
 - **Token Expired / Missing (`FIGMA_TOKEN_EXPIRED_OR_INVALID` / `isTokenExpiredOrInvalid`)**:
   - Alert the user that their Figma access token is missing, invalid, or expired.
-  - Instruct the user to create a token in **Figma Settings $\rightarrow$ Personal Access Tokens** and export `FIGMA_ACCESS_TOKEN=your_token` or update `.env`.
+  - Instruct the user to create a token in **Figma Settings $\rightarrow$ Personal Access Tokens** and configure `FIGMA_ACCESS_TOKEN` in their environment or workspace `.env` file.
 - **Node Not Found**:
   - Alert the user that the node ID could not be found in the specified file.
 - **Corporate Proxy / Self-Signed SSL (`FIGMA_SSL_CERTIFICATE_ERROR`)**:
-  - Instruct the user to add `FIGMA_IGNORE_SSL=true` to `.env` or export it in their environment.
+  - Instruct the user to add `FIGMA_IGNORE_SSL=true` to `.env` or set it in their environment.
 - **Rate Limited (`FIGMA_RATE_LIMIT_EXCEEDED` / `FIGMA_CIRCUIT_BREAKER_ACTIVE`)**:
   - Figma REST API has strict per-minute and monthly rate limits. If rate limited or the circuit breaker trips, report the cooldown to the user and suggest duplicating the file in Figma Drafts to get a fresh URL.

package/figma-to-code/scripts/fetch_figma.js

@@ -11,27 +11,138 @@ const { URL } = require('url');
 // Environment and Auth Utilities
 // -----------------------------------------------------------------------------
 
-function loadEnv() {
-  const home = process.env.HOME || '';
-  const candidates = [
-    path.join(process.cwd(), '.env'),
+function resolveHomeDir() {
+  return (
+    process.env.HOME ||
+    process.env.USERPROFILE ||
+    (typeof os.homedir === 'function' ? os.homedir() : '') ||
+    ''
+  );
+}
+
+function decodeEnvBuffer(buf) {
+  if (!Buffer.isBuffer(buf)) {
+    const str = String(buf || '');
+    return str.charCodeAt(0) === 0xfeff ? str.slice(1) : str;
+  }
+  if (buf.length >= 2 && buf[0] === 0xff && buf[1] === 0xfe) {
+    return buf.toString('utf16le', 2);
+  }
+  const str = buf.toString('utf8');
+  return str.charCodeAt(0) === 0xfeff ? str.slice(1) : str;
+}
+
+function getPowerShellProfilePaths(home) {
+  const paths = [];
+  if (process.env.PROFILE && process.env.PROFILE.toLowerCase().endsWith('.ps1')) {
+    paths.push(process.env.PROFILE);
+  }
+
+  const docRoots = [];
+  if (home) {
+    docRoots.push(
+      path.join(home, 'Documents'),
+      path.join(home, 'Documentos'),
+      path.join(home, 'OneDrive', 'Documents'),
+      path.join(home, 'OneDrive', 'Documentos'),
+    );
+  }
+
+  const oneDriveEnvs = [
+    process.env.OneDrive,
+    process.env.OneDriveConsumer,
+    process.env.OneDriveCommercial,
+  ].filter(Boolean);
+
+  for (const od of oneDriveEnvs) {
+    docRoots.push(path.join(od, 'Documents'), path.join(od, 'Documentos'));
+  }
+
+  const shellDirs = ['PowerShell', 'WindowsPowerShell'];
+  const profileFiles = [
+    'Microsoft.PowerShell_profile.ps1',
+    'Microsoft.VSCode_profile.ps1',
+    'profile.ps1',
+  ];
+
+  for (const docRoot of docRoots) {
+    if (!fs.existsSync(docRoot)) continue;
+    for (const shellDir of shellDirs) {
+      const fullShellDir = path.join(docRoot, shellDir);
+      if (!fs.existsSync(fullShellDir)) continue;
+      for (const profileFile of profileFiles) {
+        paths.push(path.join(fullShellDir, profileFile));
+      }
+    }
+  }
+
+  if (home) {
+    const xdgPsDir = path.join(process.env.XDG_CONFIG_HOME || path.join(home, '.config'), 'powershell');
+    if (fs.existsSync(xdgPsDir)) {
+      for (const profileFile of profileFiles) {
+        paths.push(path.join(xdgPsDir, profileFile));
+      }
+    }
+  }
+
+  return Array.from(new Set(paths));
+}
+
+function loadEnv(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const home = options.home !== undefined ? options.home : resolveHomeDir();
+
+  const dotEnvCandidates = [
+    path.join(cwd, '.env'),
+    path.join(cwd, '.env.local'),
     home ? path.join(home, '.env') : null,
+  ].filter(Boolean);
+
+  const shellConfigCandidates = [
     home ? path.join(home, '.zshrc') : null,
+    home ? path.join(home, '.zprofile') : null,
+    home ? path.join(home, '.zshenv') : null,
     home ? path.join(home, '.bashrc') : null,
+    home ? path.join(home, '.bash_profile') : null,
+    home ? path.join(home, '.profile') : null,
+    ...getPowerShellProfilePaths(home),
   ].filter(Boolean);
 
-  for (const envPath of candidates) {
-    if (fs.existsSync(envPath)) {
+  const seen = new Set();
+  const candidates = [];
+  for (const p of dotEnvCandidates) {
+    if (!seen.has(p)) {
+      seen.add(p);
+      candidates.push({ filePath: p, isShellConfig: false });
+    }
+  }
+  for (const p of shellConfigCandidates) {
+    if (!seen.has(p)) {
+      seen.add(p);
+      candidates.push({ filePath: p, isShellConfig: true });
+    }
+  }
+
+  for (const { filePath, isShellConfig } of candidates) {
+    if (fs.existsSync(filePath)) {
       try {
-        const envContent = fs.readFileSync(envPath, 'utf8');
-        const lines = envContent.split('\n');
+        const rawBuf = fs.readFileSync(filePath);
+        const envContent = decodeEnvBuffer(rawBuf);
+        if (isShellConfig && !/figma_/i.test(envContent)) {
+          continue;
+        }
+        const lines = envContent.split(/\r?\n/);
         for (const line of lines) {
+          if (isShellConfig && !/figma_/i.test(line)) {
+            continue;
+          }
           const parsed = parseEnvLine(line);
           if (parsed && parsed.key) {
+            const isFigmaVar = /^FIGMA_/i.test(parsed.key);
+            const envKey = isFigmaVar ? parsed.key.toUpperCase() : parsed.key;
             // For dot-env files, load any variable; for shell configs, only load FIGMA_ variables
-            const isShellConfig = envPath.endsWith('.zshrc') || envPath.endsWith('.bashrc');
-            if (!process.env[parsed.key] && (!isShellConfig || parsed.key.startsWith('FIGMA_'))) {
-              process.env[parsed.key] = parsed.val;
+            if (!process.env[envKey] && (!isShellConfig || isFigmaVar)) {
+              process.env[envKey] = parsed.val;
             }
           }
         }
@@ -44,16 +155,47 @@ function loadEnv() {
 
 function parseEnvLine(line) {
   if (!line || typeof line !== 'string') return null;
-  let trimmed = line.trim();
-  if (trimmed.startsWith('export ')) {
-    trimmed = trimmed.substring(7).trim();
+  let trimmed = line.replace(/^\uFEFF/, '').trim();
+  if (!trimmed || trimmed.startsWith('#')) {
+    return null;
   }
-  if (!trimmed || trimmed.startsWith('#') || !trimmed.includes('=')) {
+
+  // Handle PowerShell [Environment]::SetEnvironmentVariable("KEY", "VAL", ...)
+  const setEnvMatch = trimmed.match(
+    /^\[(?:System\.)?Environment\]::SetEnvironmentVariable\(\s*(['"])([A-Za-z_][A-Za-z0-9_]*)\1\s*,\s*(['"])([^'"]*)\3/i,
+  );
+  if (setEnvMatch) {
+    return { key: setEnvMatch[2], val: setEnvMatch[4] };
+  }
+
+  // Strip Unix 'export ' or Windows CMD 'set ' prefix (requires whitespace after keyword)
+  if (/^export\s+/i.test(trimmed)) {
+    trimmed = trimmed.replace(/^export\s+/i, '').trim();
+  } else if (/^set\s+/i.test(trimmed)) {
+    trimmed = trimmed.replace(/^set\s+/i, '').trim();
+    if (trimmed.startsWith('"') && trimmed.endsWith('"') && trimmed.includes('=')) {
+      trimmed = trimmed.slice(1, -1).trim();
+    }
+  }
+
+  if (!trimmed.includes('=')) {
     return null;
   }
 
   const eqIdx = trimmed.indexOf('=');
-  const key = trimmed.slice(0, eqIdx).trim();
+  let key = trimmed.slice(0, eqIdx).trim();
+
+  // Strip PowerShell $env:KEY or ${env:KEY} syntax
+  if (/^\$env:/i.test(key)) {
+    key = key.replace(/^\$env:/i, '').trim();
+  } else if (/^\$\{env:([^}]+)\}$/i.test(key)) {
+    key = key.replace(/^\$\{env:([^}]+)\}$/i, '$1').trim();
+  }
+
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+    return null;
+  }
+
   let rest = trimmed.slice(eqIdx + 1).trim();
 
   let val = '';
@@ -566,7 +708,7 @@ const MAX_REQUESTS_PER_WINDOW = 5; // Max 5 calls per minute (well below Figma 1
 const MIN_REQUEST_INTERVAL_MS = 2500; // Minimum 2.5s between consecutive requests
 
 function getRateGateFilePath() {
-  const home = process.env.HOME || (typeof os.homedir === 'function' ? os.homedir() : '');
+  const home = resolveHomeDir();
   return home ? path.join(home, '.figma_ratelimit.json') : path.join(process.cwd(), '.figma_ratelimit.json');
 }
 
@@ -1173,7 +1315,7 @@ function formatApiError(error) {
   } else if (error.statusCode === 401 || error.statusCode === 403) {
     isTokenExpiredOrInvalid = true;
     errorMessage =
-      'FIGMA_TOKEN_EXPIRED_OR_INVALID: The provided Figma access token is expired, invalid, or unauthorized. Create a new token in Figma Settings -> Personal Access Tokens and export FIGMA_ACCESS_TOKEN or add it to .env.';
+      'FIGMA_TOKEN_EXPIRED_OR_INVALID: The provided Figma access token is expired, invalid, or unauthorized. Create a new token in Figma Settings -> Personal Access Tokens and set FIGMA_ACCESS_TOKEN in your environment or workspace .env file.';
   } else if (error.statusCode === 429) {
     isRateLimited = true;
     let retryMsg = ' Please wait 30-60 seconds before making more requests.';
@@ -1221,6 +1363,9 @@ function formatApiError(error) {
 
 // Export internal functions for unit testing
 module.exports = {
+  resolveHomeDir,
+  decodeEnvBuffer,
+  getPowerShellProfilePaths,
   loadEnv,
   parseEnvLine,
   getFigmaToken,

package/figma-to-code/scripts/test_fetch_figma.js

@@ -1,7 +1,11 @@
 #!/usr/bin/env node
 
 const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
 const {
+  decodeEnvBuffer,
   loadEnv,
   parseEnvLine,
   parseFigmaUrl,
@@ -70,6 +74,81 @@ test('parseEnvLine: returns null for comments, empty lines, and lines without eq
   assert.strictEqual(parseEnvLine('export FIGMA_TOKEN'), null);
 });
 
+test('parseEnvLine: parses Windows PowerShell $env: syntax, CRLF, and SetEnvironmentVariable', () => {
+  assert.deepStrictEqual(
+    parseEnvLine('$env:FIGMA_ACCESS_TOKEN="figd_win_ps1"\r\n'),
+    { key: 'FIGMA_ACCESS_TOKEN', val: 'figd_win_ps1' }
+  );
+  assert.deepStrictEqual(
+    parseEnvLine("$Env:FIGMA_ACCESS_TOKEN = 'figd_win_single' # ps comment\r\n"),
+    { key: 'FIGMA_ACCESS_TOKEN', val: 'figd_win_single' }
+  );
+  assert.deepStrictEqual(
+    parseEnvLine('${env:FIGMA_TOKEN}="figd_braced"'),
+    { key: 'FIGMA_TOKEN', val: 'figd_braced' }
+  );
+  assert.deepStrictEqual(
+    parseEnvLine('[System.Environment]::SetEnvironmentVariable("FIGMA_ACCESS_TOKEN", "figd_sys_env", "User")'),
+    { key: 'FIGMA_ACCESS_TOKEN', val: 'figd_sys_env' }
+  );
+});
+
+test('parseEnvLine: parses Windows CMD set syntax without corrupting SETTINGS/EXPORT keys', () => {
+  assert.deepStrictEqual(
+    parseEnvLine('set FIGMA_ACCESS_TOKEN=figd_cmd_plain\r\n'),
+    { key: 'FIGMA_ACCESS_TOKEN', val: 'figd_cmd_plain' }
+  );
+  assert.deepStrictEqual(
+    parseEnvLine('set "FIGMA_ACCESS_TOKEN=figd_cmd_quoted"'),
+    { key: 'FIGMA_ACCESS_TOKEN', val: 'figd_cmd_quoted' }
+  );
+  assert.deepStrictEqual(
+    parseEnvLine('SETTINGS=enabled'),
+    { key: 'SETTINGS', val: 'enabled' }
+  );
+  assert.deepStrictEqual(
+    parseEnvLine('EXPORT_MODE=fast'),
+    { key: 'EXPORT_MODE', val: 'fast' }
+  );
+  assert.strictEqual(parseEnvLine('$MaximumHistoryCount = 4096'), null);
+});
+
+test('loadEnv & decodeEnvBuffer: loads FIGMA_ vars from UTF-16LE PowerShell profile and ignores non-FIGMA_ vars', () => {
+  const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'figma-to-code-win-env-'));
+  const savedAccess = process.env.FIGMA_ACCESS_TOKEN;
+  const savedOther = process.env.UNRELATED_PS_SECRET;
+  delete process.env.FIGMA_ACCESS_TOKEN;
+  delete process.env.UNRELATED_PS_SECRET;
+
+  try {
+    const psDir = path.join(tmpRoot, 'Documents', 'PowerShell');
+    fs.mkdirSync(psDir, { recursive: true });
+    const psFile = path.join(psDir, 'Microsoft.PowerShell_profile.ps1');
+
+    const psContent = '$env:FIGMA_ACCESS_TOKEN="figd_utf16_ps7"\r\n$env:UNRELATED_PS_SECRET="should_not_leak"\r\n';
+    const utf16WithBom = Buffer.concat([Buffer.from([0xff, 0xfe]), Buffer.from(psContent, 'utf16le')]);
+    fs.writeFileSync(psFile, utf16WithBom);
+
+    assert.ok(decodeEnvBuffer(utf16WithBom).includes('figd_utf16_ps7'));
+
+    loadEnv({ cwd: tmpRoot, home: tmpRoot });
+    assert.strictEqual(process.env.FIGMA_ACCESS_TOKEN, 'figd_utf16_ps7');
+    assert.strictEqual(process.env.UNRELATED_PS_SECRET, undefined);
+
+    // Case-insensitive PowerShell $env:figma_access_token normalization
+    delete process.env.FIGMA_ACCESS_TOKEN;
+    fs.writeFileSync(psFile, '$env:figma_access_token="figd_lowercase_ps7"\r\n', 'utf8');
+    loadEnv({ cwd: tmpRoot, home: tmpRoot });
+    assert.strictEqual(process.env.FIGMA_ACCESS_TOKEN, 'figd_lowercase_ps7');
+  } finally {
+    if (savedAccess !== undefined) process.env.FIGMA_ACCESS_TOKEN = savedAccess;
+    else delete process.env.FIGMA_ACCESS_TOKEN;
+    if (savedOther !== undefined) process.env.UNRELATED_PS_SECRET = savedOther;
+    else delete process.env.UNRELATED_PS_SECRET;
+    fs.rmSync(tmpRoot, { recursive: true, force: true });
+  }
+});
+
 // 1. URL Parsing Tests
 test('parseFigmaUrl: extracts fileKey and nodeId with hyphens', () => {
   const url = 'https://www.figma.com/design/1KP9pVQ1ptZzHa3Gcpr6ta/Consulta-e-pagamento?node-id=4023-474&t=abcd';

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@pedroab0/skills",
-  "version": "1.0.0",
-  "description": "Curated collection of modular, production-ready skills for AI coding agents (Claude Code, Cursor, OpenCode, Antigravity)",
+  "version": "1.1.0",
+  "description": "Curated collection of modular, production-ready skills for AI coding agents (Claude Code, Cursor, Kiro, OpenCode, Antigravity)",
   "bin": {
     "skills": "bin/cli.js",
     "skills-installer": "bin/cli.js"
   },
   "main": "./bin/cli.js",
+  "engines": {
+    "node": ">=16.7.0"
+  },
   "scripts": {
     "test": "node figma-extractor/scripts/test_fetch_figma.js && node figma-to-code/scripts/test_fetch_figma.js && node figma-node-builder/scripts/test_inspect_spec.js && node test/test_cli.js",
     "install-skills": "node ./bin/cli.js"
@@ -20,6 +23,7 @@
     "skills",
     "claude-code",
     "cursor",
+    "kiro",
     "antigravity",
     "opencode",
     "figma",
@@ -36,6 +40,7 @@
     "figma-to-code",
     "figma-extractor",
     "figma-node-builder",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ]
 }