extrafigma 0.1.0__py3-none-any.whl

extrafigma/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

extrafigma/api.py

@@ -0,0 +1,117 @@
+import time
+from typing import Optional
+
+import httpx
+
+BASE_URL = "https://api.figma.com/v1"
+# Figma returns very large Retry-After values for monthly quota exhaustion.
+# We cap the sleep and surface a clear error instead.
+_MAX_RETRY_SLEEP = 60.0
+
+
+class FigmaAPIError(Exception):
+    def __init__(self, status_code: int, message: str):
+        self.status_code = status_code
+        super().__init__(f"Figma API {status_code}: {message}")
+
+
+class FigmaAuthError(FigmaAPIError):
+    pass
+
+
+class FigmaNotFoundError(FigmaAPIError):
+    pass
+
+
+class FigmaPermissionError(FigmaAPIError):
+    pass
+
+
+class FigmaRateLimitError(FigmaAPIError):
+    def __init__(self, retry_after: Optional[float] = None, quota_exhausted: bool = False):
+        self.retry_after = retry_after
+        self.quota_exhausted = quota_exhausted
+        msg = (
+            "Monthly API quota exhausted. Resets on the 1st of next month.\n"
+            "  Upgrade your Figma seat to Dev/Full for 10 req/min instead of 6/month."
+            if quota_exhausted
+            else "Rate limited after retries"
+        )
+        super().__init__(429, msg)
+
+
+class FigmaClient:
+    def __init__(self, pat: str):
+        self._client = httpx.Client(
+            headers={"X-Figma-Token": pat},
+            timeout=90.0,
+        )
+
+    def _get(self, path: str, params: Optional[dict] = None) -> dict:
+        url = f"{BASE_URL}{path}"
+        for attempt in range(3):
+            resp = self._client.get(url, params=params or {})
+            if resp.status_code == 200:
+                return resp.json()
+            if resp.status_code == 429:
+                retry_after = float(resp.headers.get("Retry-After", 10))
+                # Large values (>5 min) indicate monthly quota exhaustion, not a burst limit.
+                if retry_after > _MAX_RETRY_SLEEP:
+                    raise FigmaRateLimitError(retry_after=retry_after, quota_exhausted=True)
+                print(f"  Rate limited. Waiting {retry_after:.0f}s...")
+                time.sleep(retry_after)
+                continue
+            if resp.status_code == 401:
+                raise FigmaAuthError(401, "Invalid PAT. Run: extrafigma auth login")
+            if resp.status_code == 404:
+                raise FigmaNotFoundError(404, f"Not found: {path}")
+            if resp.status_code == 403:
+                raise FigmaPermissionError(403, resp.text[:200])
+            resp.raise_for_status()
+        raise FigmaRateLimitError()
+
+    def get_file(self, file_key: str) -> dict:
+        return self._get(f"/files/{file_key}", params={"geometry": "paths"})
+
+    def get_nodes(self, file_key: str, node_ids: list[str]) -> dict:
+        """Return {node_id: document_node} for the given node IDs."""
+        if not node_ids:
+            return {}
+        data = self._get(
+            f"/files/{file_key}/nodes",
+            params={"ids": ",".join(node_ids)},
+        )
+        return {
+            nid: info.get("document", {})
+            for nid, info in data.get("nodes", {}).items()
+            if info
+        }
+
+    def get_images(
+        self,
+        file_key: str,
+        ids: list[str],
+        scale: int = 2,
+        format: str = "png",
+    ) -> dict:
+        """Return {node_id: signed_url}. Batches handled by caller."""
+        if not ids:
+            return {}
+        params: dict = {"ids": ",".join(ids), "format": format}
+        if format == "png":
+            params["scale"] = scale
+        elif format == "svg":
+            params["svg_outline_text"] = "false"   # keep <text> elements, not paths
+            params["svg_include_id"] = "false"
+            params["svg_simplify_stroke"] = "true"
+        data = self._get(f"/images/{file_key}", params=params)
+        return data.get("images", {})
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "FigmaClient":
+        return self
+
+    def __exit__(self, *_) -> None:
+        self.close()

extrafigma/auth.py

@@ -0,0 +1,33 @@
+import json
+import stat
+from pathlib import Path
+
+
+def get_credentials_path() -> Path:
+    config_dir = Path.home() / ".config" / "extrafigma"
+    config_dir.mkdir(parents=True, exist_ok=True)
+    return config_dir / "credentials.json"
+
+
+def save_pat(pat: str) -> None:
+    path = get_credentials_path()
+    path.write_text(json.dumps({"pat": pat}, indent=2))
+    path.chmod(stat.S_IRUSR | stat.S_IWUSR)
+
+
+def load_pat() -> str:
+    path = get_credentials_path()
+    if not path.exists():
+        return ""
+    try:
+        return json.loads(path.read_text()).get("pat", "")
+    except (json.JSONDecodeError, OSError):
+        return ""
+
+
+def delete_credentials() -> bool:
+    path = get_credentials_path()
+    if path.exists():
+        path.unlink()
+        return True
+    return False

extrafigma/cli.py

@@ -0,0 +1,95 @@
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.text import Text
+
+from extrafigma.auth import load_pat, save_pat, delete_credentials, get_credentials_path
+from extrafigma.utils.file_key import parse_file_key
+
+console = Console()
+app = typer.Typer(
+    name="extrafigma",
+    help="Pull Figma files into agent-readable local folders.",
+    no_args_is_help=True,
+)
+auth_app = typer.Typer(help="Manage your Figma Personal Access Token.")
+app.add_typer(auth_app, name="auth")
+
+
+def _require_pat() -> str:
+    """Return stored PAT, prompting the user to set one if not found."""
+    pat = load_pat()
+    if pat:
+        return pat
+    console.print("[yellow]No Figma PAT found.[/yellow] You only need to do this once.\n")
+    console.print("[dim]Get yours at: Figma → Settings → Security → Personal Access Tokens[/dim]")
+    console.print("[dim]Required scopes: file_content:read, file_metadata:read[/dim]\n")
+    pat = typer.prompt("Paste your Figma PAT", hide_input=True).strip()
+    if not pat:
+        console.print("[red]✗ No PAT provided.[/red]")
+        raise typer.Exit(1)
+    save_pat(pat)
+    console.print("[green]✓ PAT saved — won't ask again.[/green]\n")
+    return pat
+
+
+@auth_app.command("login")
+def auth_login(
+    pat: Optional[str] = typer.Option(None, "--pat", help="PAT to store (skips interactive prompt)"),
+):
+    """Store your Figma Personal Access Token."""
+    if pat:
+        pat = pat.strip()
+    else:
+        console.print("[dim]Generate a PAT at: Figma → Settings → Security → Personal Access Tokens[/dim]")
+        console.print("[dim]Required scopes: file_content:read, file_metadata:read[/dim]\n")
+        pat = typer.prompt("Paste your Figma PAT", hide_input=True).strip()
+    if not pat:
+        console.print("[red]✗ No PAT provided.[/red]")
+        raise typer.Exit(1)
+    save_pat(pat)
+    console.print("[green]✓ PAT saved.[/green]")
+
+
+@auth_app.command("status")
+def auth_status():
+    """Show PAT status."""
+    creds = get_credentials_path()
+    if not creds.exists():
+        console.print("[red]✗ No PAT stored.[/red] Run: extrafigma auth login")
+        raise typer.Exit(1)
+    pat = load_pat()
+    if not pat:
+        console.print("[red]✗ credentials.json exists but PAT is empty.[/red]")
+        raise typer.Exit(1)
+    masked = pat[:8] + "..." + pat[-4:] if len(pat) > 12 else "***"
+    console.print(f"[green]✓ PAT set[/green] ({masked})")
+    console.print(f"  Stored at: {creds}")
+
+
+@auth_app.command("logout")
+def auth_logout():
+    """Remove stored credentials."""
+    if delete_credentials():
+        console.print("[green]✓ Credentials removed.[/green]")
+    else:
+        console.print("No credentials to remove.")
+
+
+@app.command()
+def pull(
+    url: str = typer.Argument(..., help="Figma file URL or file key"),
+    folder: str = typer.Argument(..., help="Output folder path"),
+):
+    """Pull a Figma file to a local agent-readable folder."""
+    from extrafigma.puller.pull import pull as do_pull
+
+    pat = _require_pat()
+
+    file_key = parse_file_key(url)
+    if not file_key:
+        console.print(f"[red]✗ Could not parse a file key from:[/red] {url}")
+        raise typer.Exit(1)
+
+    do_pull(file_key=file_key, figma_url=url, output_dir=folder, pat=pat)

extrafigma/puller/distiller.py

@@ -0,0 +1,206 @@
+import re
+
+from extrafigma.utils.color import rgba_to_hex, find_nearest
+from extrafigma.utils.layout import distill_layout
+
+
+def _safe_name(name: str) -> str:
+    name = name.lower().replace(" ", "-")
+    name = re.sub(r"[^a-z0-9-]", "", name)
+    return name or "unnamed"
+
+
+class Distiller:
+    def __init__(self, color_map: dict, type_map: dict):
+        self.color_map = color_map  # hex -> token_name
+        self.type_map = type_map    # styleId -> token_name
+        # Populated during distillation: node_id -> filename (e.g. "icon-name.svg")
+        self.svg_ids: dict[str, str] = {}
+
+    def distill(self, node: dict) -> dict:
+        ntype = node.get("type", "UNKNOWN")
+        handlers = {
+            "FRAME": self._frame,
+            "COMPONENT": self._frame,
+            "COMPONENT_SET": self._frame,
+            "SECTION": self._frame,
+            "GROUP": self._group,
+            "TEXT": self._text,
+            "INSTANCE": self._instance,
+            "RECTANGLE": self._rect,
+            "ELLIPSE": self._rect,
+            "LINE": self._rect,
+            "VECTOR": self._vector,
+            "BOOLEAN_OPERATION": self._vector,
+            "IMAGE": self._image,
+        }
+        handler = handlers.get(ntype)
+        if handler:
+            return handler(node)
+        return {"type": "UNKNOWN", "nodeType": ntype, "name": node.get("name", "")}
+
+    # ── children ───────────────────────────────────────────────────────────────
+
+    def _children(self, node: dict, absolute: bool = False) -> list:
+        out = []
+        for child in node.get("children", []):
+            if child.get("type") == "GROUP":
+                out.extend(self._flatten_group(child, absolute=absolute))
+            else:
+                distilled = self.distill(child)
+                if absolute:
+                    bb = child.get("absoluteBoundingBox") or {}
+                    if bb.get("x") is not None:
+                        distilled["x"] = bb["x"]
+                    if bb.get("y") is not None:
+                        distilled["y"] = bb["y"]
+                out.append(distilled)
+        return out
+
+    def _flatten_group(self, group: dict, absolute: bool = False) -> list:
+        out = []
+        for child in group.get("children", []):
+            if child.get("type") == "GROUP":
+                out.extend(self._flatten_group(child, absolute=absolute))
+            else:
+                distilled = self.distill(child)
+                if absolute:
+                    bb = child.get("absoluteBoundingBox") or {}
+                    if bb.get("x") is not None:
+                        distilled["x"] = bb["x"]
+                    if bb.get("y") is not None:
+                        distilled["y"] = bb["y"]
+                out.append(distilled)
+        return out
+
+    # ── node handlers ──────────────────────────────────────────────────────────
+
+    def _frame(self, node: dict) -> dict:
+        bb = node.get("absoluteBoundingBox") or node.get("absoluteRenderBounds") or {}
+        layout = distill_layout(node)
+        is_absolute = layout.get("mode") == "absolute"
+        result: dict = {
+            "type": "FRAME",
+            "name": node.get("name", ""),
+            "width": bb.get("width"),
+            "height": bb.get("height"),
+            "layout": layout,
+            "background": self._fills(node.get("fills", [])),
+            "borderRadius": node.get("cornerRadius") or 0,
+        }
+        children = self._children(node, absolute=is_absolute)
+        if children:
+            result["children"] = children
+        return result
+
+    def _group(self, node: dict) -> dict:
+        bb = node.get("absoluteBoundingBox") or {}
+        result: dict = {
+            "type": "FRAME",
+            "name": node.get("name", ""),
+            "width": bb.get("width"),
+            "height": bb.get("height"),
+            "layout": {"mode": "absolute"},
+            "background": "transparent",
+            "borderRadius": 0,
+        }
+        children = self._flatten_group(node, absolute=True)
+        if children:
+            result["children"] = children
+        return result
+
+    def _text(self, node: dict) -> dict:
+        style = node.get("style", {})
+        bb = node.get("absoluteBoundingBox") or {}
+        out: dict = {
+            "type": "TEXT",
+            "name": node.get("name", ""),
+            "content": node.get("characters", ""),
+            "style": self._type(node),
+            "color": self._fills(node.get("fills", [])),
+            "align": style.get("textAlignHorizontal", "LEFT").lower(),
+        }
+        if node.get("layoutSizingHorizontal") == "FIXED" and bb.get("width"):
+            out["maxWidth"] = bb["width"]
+        return out
+
+    def _instance(self, node: dict) -> dict:
+        return {
+            "type": "INSTANCE",
+            "name": node.get("name", ""),
+            "component": node.get("name", ""),
+            "props": {},
+        }
+
+    def _rect(self, node: dict) -> dict:
+        bb = node.get("absoluteBoundingBox") or node.get("absoluteRenderBounds") or {}
+        return {
+            "type": "RECTANGLE",
+            "name": node.get("name", ""),
+            "width": bb.get("width"),
+            "height": bb.get("height"),
+            "fill": self._fills(node.get("fills", [])),
+            "borderRadius": node.get("cornerRadius") or 0,
+        }
+
+    def _vector(self, node: dict) -> dict:
+        node_id = node.get("id", "")
+        filename = f"{_safe_name(node.get('name', 'vector'))}.svg"
+        if node_id:
+            # Deduplicate: same name → same file
+            self.svg_ids[node_id] = filename
+        return {
+            "type": "VECTOR",
+            "name": node.get("name", ""),
+            "src": f"assets/{filename}",
+        }
+
+    def _image(self, node: dict) -> dict:
+        bb = node.get("absoluteBoundingBox") or {}
+        return {
+            "type": "IMAGE",
+            "name": node.get("name", ""),
+            "src": f"assets/{_safe_name(node.get('name', 'image'))}.png",
+            "width": bb.get("width"),
+            "height": bb.get("height"),
+        }
+
+    # ── token resolution ───────────────────────────────────────────────────────
+
+    def _fills(self, fills: list) -> str:
+        visible = [f for f in fills if f.get("visible", True)]
+        if not visible:
+            return "transparent"
+        fill = visible[0]
+        ftype = fill.get("type", "")
+        if ftype == "IMAGE":
+            return "image"
+        if ftype != "SOLID":
+            return "gradient"
+
+        hex_val = rgba_to_hex(fill.get("color", {}))
+        opacity = fill.get("opacity", 1.0)
+
+        if hex_val in self.color_map:
+            name = self.color_map[hex_val]
+            return f"colors/{name}/{int(opacity * 100)}" if opacity < 1.0 else f"colors/{name}"
+
+        nearest = find_nearest(hex_val, self.color_map, tolerance=2)
+        if nearest:
+            return f"colors/{nearest}  # ~approx"
+
+        return f"#{hex_val}  # not in tokens"
+
+    def _type(self, node: dict) -> "str | dict":
+        styles_ref = node.get("styles", {})
+        sid = styles_ref.get("text") or node.get("textStyleId")
+        if sid and sid in self.type_map:
+            return f"typography/{self.type_map[sid]}"
+        style = node.get("style", {})
+        return {
+            "fontFamily": style.get("fontFamily"),
+            "fontSize": style.get("fontSize"),
+            "fontWeight": style.get("fontWeight"),
+            "lineHeight": style.get("lineHeightPx"),
+            "letterSpacing": style.get("letterSpacing", 0),
+        }

extrafigma/puller/index_writer.py

@@ -0,0 +1,51 @@
+from pathlib import Path
+
+
+def write_index_md(
+    output_dir: Path,
+    file_name: str,
+    figma_url: str,
+    pages: list[dict],
+    tokens: dict,
+    pulled_at: str,
+) -> None:
+    frame_count = sum(
+        len([c for c in p.get("children", []) if c.get("type") != "SLICE"])
+        for p in pages
+    )
+    color_count = len(tokens.get("color_tokens", {}))
+    type_count = len(tokens.get("type_tokens", {}))
+    date = pulled_at[:10]
+
+    lines = [
+        f"# {file_name}",
+        "",
+        f"Pulled from Figma on {date}. {len(pages)} page{'s' if len(pages) != 1 else ''}, {frame_count} frames.",
+        "",
+        "## How to use this folder",
+        "1. Read `tokens/` first — use token names, never raw values.",
+        "2. For each screen: read `page.md`, then each `frame.json` + `.png`.",
+        "3. Use the `.png` as the visual reference to verify your implementation.",
+        "",
+        "## Pages",
+        "",
+    ]
+
+    for page in pages:
+        pname = page.get("name", "Page")
+        frames = [c for c in page.get("children", []) if c.get("type") != "SLICE"]
+        lines.append(f"### {pname} ({len(frames)} frames)")
+        lines.append(f"→ pages/{pname}/page.md")
+        lines.append("")
+
+    lines += [
+        "## Design tokens",
+        "",
+        f"→ tokens/colors.json — {color_count} color{'s' if color_count != 1 else ''}",
+        f"→ tokens/typography.json — {type_count} type style{'s' if type_count != 1 else ''}",
+        "",
+        "## Source",
+        f"→ {figma_url}",
+    ]
+
+    (output_dir / "index.md").write_text("\n".join(lines))

extrafigma/puller/page_writer.py

@@ -0,0 +1,38 @@
+from pathlib import Path
+
+
+def write_page_md(page_dir: Path, page_node: dict) -> None:
+    name = page_node.get("name", "Page")
+    frames = [c for c in page_node.get("children", []) if c.get("type") != "SLICE"]
+
+    lines = [
+        f"# {name}",
+        "",
+        f"> {len(frames)} frame{'s' if len(frames) != 1 else ''}",
+        "",
+    ]
+
+    for frame in frames:
+        fname = frame.get("name", "Frame")
+        bb = frame.get("absoluteBoundingBox") or {}
+        w = bb.get("width")
+        h = bb.get("height")
+        size = f"{int(w)}×{int(h)}" if w and h else ""
+
+        layout_mode = frame.get("layoutMode", "NONE")
+        if layout_mode == "HORIZONTAL":
+            layout_desc = "Flex row."
+        elif layout_mode == "VERTICAL":
+            layout_desc = "Flex column."
+        else:
+            layout_desc = "Absolute positioning."
+
+        header = f"## {fname}"
+        if size:
+            header += f" ({size})"
+        lines.append(header)
+        lines.append(layout_desc)
+        lines.append(f"→ {fname}.frame.json | {fname}.png")
+        lines.append("")
+
+    (page_dir / "page.md").write_text("\n".join(lines))

extrafigma/puller/pull.py

@@ -0,0 +1,176 @@
+import json
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+
+from extrafigma.api import FigmaClient, FigmaAuthError, FigmaNotFoundError, FigmaPermissionError, FigmaRateLimitError
+from extrafigma.puller.distiller import Distiller
+from extrafigma.puller.token_extractor import TokenExtractor
+from extrafigma.puller.renderer import export_frames, export_svgs
+from extrafigma.puller.page_writer import write_page_md
+from extrafigma.puller.index_writer import write_index_md
+from extrafigma.puller.snapshot import write_meta
+
+_CLAUDE_MD = """\
+# ExtraFigma — Agent Instructions
+
+This folder was produced by `extrafigma pull`. It contains a complete,
+distilled representation of a Figma design file.
+
+## Start here
+1. Read `index.md` — overview of all pages and frames
+2. Read `tokens/colors.json` and `tokens/typography.json`
+3. For each frame: read `page.md`, then `<Frame>.frame.json`, then open `<Frame>.png`
+
+## The implementation loop (per frame)
+1. Read the frame.json — this is the exact layout spec
+2. Open the .png — this is the visual ground truth
+3. Implement the component
+4. Visually compare your output to the .png
+5. Fix any discrepancies, then move to the next frame
+
+## Rules
+- NEVER hardcode a color. Always use a token: `colors/brand-blue`
+- NEVER hardcode a font size. Always use a token: `typography/heading-xl`
+- When you see `type: INSTANCE`, use the matching component from your codebase
+- When you see `type: VECTOR`, use the `.svg` file at the `src` path
+- The .png is always right. If frame.json and .png disagree, follow the .png
+
+## Layout translation
+
+| frame.json                       | CSS                             |
+|----------------------------------|---------------------------------|
+| layout.direction: "row"          | flex-direction: row             |
+| layout.direction: "column"       | flex-direction: column          |
+| layout.mainAxis: "center"        | justify-content: center         |
+| layout.mainAxis: "flex-start"    | justify-content: flex-start     |
+| layout.mainAxis: "space-between" | justify-content: space-between  |
+| layout.crossAxis: "center"       | align-items: center             |
+| layout.gap: 24                   | gap: 24px                       |
+| layout.padding.*                 | padding: top right bottom left  |
+| widthMode: "fill"                | flex: 1 / width: 100%           |
+| widthMode: "hug"                 | width: fit-content              |
+| widthMode: "fixed"               | width: <value>px                |
+| layout.mode: "absolute"          | position: relative on parent    |
+| x / y on child of absolute frame | position: absolute; left/top   |
+
+## Token usage
+
+In CSS:    var(--colors-brand-blue)
+In Tailwind (after tailwind.config.js): text-brand-blue
+In JS/TS:  theme.colors['brand-blue']
+
+## Colors flagged `# not in tokens`
+Designer used a raw value without a named style. Use it but add a TODO comment
+for design system cleanup.
+"""
+
+
+def _safe_filename(name: str) -> str:
+    name = re.sub(r"[^\w\s-]", "", name)
+    name = re.sub(r"[\s]+", "-", name.strip())
+    return name or "unnamed"
+
+
+def pull(file_key: str, figma_url: str, output_dir: str, pat: str) -> None:
+    out = Path(output_dir)
+    out.mkdir(parents=True, exist_ok=True)
+    pulled_at = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    try:
+        with FigmaClient(pat) as api:
+            # 1. Full file
+            print("Fetching file structure...")
+            file_data = api.get_file(file_key)
+            file_name = file_data.get("name", "Figma File")
+            version = file_data.get("version", "")
+            document = file_data.get("document", {})
+            pages = document.get("children", [])
+
+            # 2. Token extraction (2-step: style node fetch + tree walk fallback)
+            print("Extracting design tokens...")
+            extractor = TokenExtractor(file_data)
+            tokens = extractor.extract(document, api=api, file_key=file_key)
+
+            tokens_dir = out / "tokens"
+            tokens_dir.mkdir(exist_ok=True)
+            (tokens_dir / "colors.json").write_text(
+                json.dumps({"source": "figma_styles", "tokens": tokens["color_tokens"]}, indent=2)
+            )
+            (tokens_dir / "typography.json").write_text(
+                json.dumps({"source": "figma_styles", "tokens": tokens["type_tokens"]}, indent=2)
+            )
+
+            # 3. Distill frames
+            print("Distilling frames...")
+            distiller = Distiller(
+                color_map=tokens["color_map"],
+                type_map=tokens["type_map"],
+            )
+
+            all_frame_ids: list[str] = []
+            id_to_png_path: dict[str, Path] = {}
+
+            for page in pages:
+                page_name = _safe_filename(page.get("name", "Page"))
+                page_dir = out / "pages" / page_name
+                page_dir.mkdir(parents=True, exist_ok=True)
+
+                top_frames = [c for c in page.get("children", []) if c.get("type") != "SLICE"]
+
+                for frame in top_frames:
+                    fname = _safe_filename(frame.get("name", "Frame"))
+                    distilled = distiller.distill(frame)
+                    (page_dir / f"{fname}.frame.json").write_text(json.dumps(distilled, indent=2))
+
+                    fid = frame.get("id", "")
+                    if fid:
+                        all_frame_ids.append(fid)
+                        id_to_png_path[fid] = page_dir / f"{fname}.png"
+
+                write_page_md(page_dir, page)
+
+            # 4. PNG export
+            print("Exporting frame PNGs...")
+            downloaded = export_frames(
+                api=api,
+                file_key=file_key,
+                frame_ids=all_frame_ids,
+                id_to_path=id_to_png_path,
+            )
+            print(f"  {downloaded}/{len(all_frame_ids)} PNGs saved.")
+
+            # 5. SVG export
+            if distiller.svg_ids:
+                print(f"Exporting {len(distiller.svg_ids)} SVG icons...")
+                assets_dir = out / "assets"
+                svg_count = export_svgs(
+                    api=api,
+                    file_key=file_key,
+                    svg_ids=distiller.svg_ids,
+                    assets_dir=assets_dir,
+                )
+                print(f"  {svg_count}/{len(distiller.svg_ids)} SVGs saved.")
+
+            # 6. Index + metadata
+            write_index_md(out, file_name, figma_url, pages, tokens, pulled_at)
+            write_meta(out, file_key, file_name, figma_url, version, pages, pulled_at)
+
+            # 7. Agent instructions
+            (out / "CLAUDE.md").write_text(_CLAUDE_MD)
+
+            print(f"\nDone. {len(all_frame_ids)} frames pulled to {out}/")
+
+    except FigmaRateLimitError as exc:
+        print(f"\n✗ {exc}")
+        raise SystemExit(1)
+    except FigmaAuthError as exc:
+        print(f"\n✗ {exc}")
+        raise SystemExit(1)
+    except FigmaNotFoundError as exc:
+        print(f"\n✗ {exc}")
+        print("  Check the URL and that you have view access in Figma.")
+        raise SystemExit(1)
+    except FigmaPermissionError as exc:
+        print(f"\n✗ Permission denied: {exc}")
+        raise SystemExit(1)

extrafigma/puller/renderer.py

@@ -0,0 +1,113 @@
+import time
+from pathlib import Path
+
+import httpx
+
+_PNG_BATCH = 20
+_SVG_BATCH = 200
+
+
+def export_frames(
+    api,
+    file_key: str,
+    frame_ids: list[str],
+    id_to_path: dict[str, Path],
+    scale: int = 2,
+) -> int:
+    """Download 2× PNGs for all frame IDs. Returns count of successfully saved files."""
+    if not frame_ids:
+        return 0
+
+    total = len(frame_ids)
+    downloaded = 0
+
+    for i in range(0, total, _PNG_BATCH):
+        batch = frame_ids[i : i + _PNG_BATCH]
+        end = min(i + _PNG_BATCH, total)
+        print(f"  Exporting frames {i + 1}–{end}/{total}...")
+
+        try:
+            urls = api.get_images(file_key, batch, scale=scale, format="png")
+        except Exception:
+            # Large frames can exceed Figma's render limit at 2×; retry at 1×
+            if scale > 1:
+                print(f"  Batch too large at {scale}×, retrying at 1×...")
+                try:
+                    urls = api.get_images(file_key, batch, scale=1, format="png")
+                except Exception as exc2:
+                    print(f"  Warning: image export failed for batch: {exc2}")
+                    continue
+            else:
+                urls = {}
+                for fid in batch:
+                    try:
+                        urls.update(api.get_images(file_key, [fid], scale=1, format="png"))
+                    except Exception as exc2:
+                        print(f"  Warning: could not export frame {fid}: {exc2}")
+
+        for frame_id, url in urls.items():
+            if not url:
+                continue
+            target = id_to_path.get(frame_id)
+            if not target:
+                continue
+            try:
+                resp = httpx.get(url, timeout=60.0, follow_redirects=True)
+                resp.raise_for_status()
+                target.parent.mkdir(parents=True, exist_ok=True)
+                target.write_bytes(resp.content)
+                downloaded += 1
+            except Exception as exc:
+                print(f"  Warning: could not download PNG for {frame_id}: {exc}")
+
+        if i + _PNG_BATCH < total:
+            time.sleep(0.5)
+
+    return downloaded
+
+
+def export_svgs(
+    api,
+    file_key: str,
+    svg_ids: dict[str, str],
+    assets_dir: Path,
+) -> int:
+    """Download SVGs for all collected VECTOR node IDs. Returns count saved."""
+    if not svg_ids:
+        return 0
+
+    assets_dir.mkdir(parents=True, exist_ok=True)
+    node_ids = list(svg_ids.keys())
+    total = len(node_ids)
+    saved = 0
+
+    for i in range(0, total, _SVG_BATCH):
+        batch = node_ids[i : i + _SVG_BATCH]
+        end = min(i + _SVG_BATCH, total)
+        print(f"  Exporting SVGs {i + 1}–{end}/{total}...")
+
+        try:
+            urls = api.get_images(file_key, batch, format="svg")
+        except Exception as exc:
+            print(f"  Warning: SVG export failed for batch: {exc}")
+            continue
+
+        for node_id, url in urls.items():
+            if not url:
+                # Node could not be rendered (e.g. remote library component)
+                continue
+            filename = svg_ids.get(node_id)
+            if not filename:
+                continue
+            try:
+                resp = httpx.get(url, timeout=30.0, follow_redirects=True)
+                resp.raise_for_status()
+                (assets_dir / filename).write_text(resp.text, encoding="utf-8")
+                saved += 1
+            except Exception as exc:
+                print(f"  Warning: could not download SVG {filename}: {exc}")
+
+        if i + _SVG_BATCH < total:
+            time.sleep(0.5)
+
+    return saved

extrafigma/puller/snapshot.py

@@ -0,0 +1,34 @@
+import json
+from pathlib import Path
+
+
+def write_meta(
+    output_dir: Path,
+    file_key: str,
+    file_name: str,
+    figma_url: str,
+    version: str,
+    pages: list[dict],
+    pulled_at: str,
+    token_source: str = "styles",
+) -> None:
+    meta_dir = output_dir / ".extrafigma"
+    meta_dir.mkdir(parents=True, exist_ok=True)
+
+    frame_count = sum(
+        len([c for c in p.get("children", []) if c.get("type") != "SLICE"])
+        for p in pages
+    )
+
+    data = {
+        "file_key": file_key,
+        "file_name": file_name,
+        "version": version,
+        "pulled_at": pulled_at,
+        "figma_url": figma_url,
+        "token_source": token_source,
+        "pages": [p.get("name", "") for p in pages],
+        "frame_count": frame_count,
+    }
+
+    (meta_dir / "meta.json").write_text(json.dumps(data, indent=2))

extrafigma/puller/token_extractor.py

@@ -0,0 +1,162 @@
+import re
+
+from extrafigma.utils.color import rgba_to_hex
+
+_NODE_BATCH = 50
+
+
+def _slugify(name: str) -> str:
+    """'Brand/Blue 500' -> 'brand-blue-500'"""
+    name = name.replace("/", "-").replace(" ", "-")
+    name = re.sub(r"[^a-zA-Z0-9-]", "", name)
+    name = re.sub(r"-+", "-", name)
+    return name.lower().strip("-")
+
+
+class TokenExtractor:
+    def __init__(self, file_data: dict):
+        # {styleId: {name, styleType, node_id}} from the top-level file response
+        self.style_meta: dict = file_data.get("styles", {})
+        self.color_map: dict[str, str] = {}          # hex -> token_name
+        self.style_id_to_color: dict[str, str] = {}  # styleId -> token_name
+        self.type_map: dict[str, str] = {}            # styleId -> token_name
+        self.color_tokens: dict[str, str] = {}        # token_name -> "#RRGGBB"
+        self.type_tokens: dict[str, dict] = {}        # token_name -> font props
+
+    def extract(self, document: dict, api=None, file_key: str = "") -> dict:
+        # Step 1: build name maps from style metadata (names only, no values yet)
+        fill_sids: list[str] = []
+        text_sids: list[str] = []
+        for sid, meta in self.style_meta.items():
+            stype = meta.get("styleType") or meta.get("style_type", "")
+            slug = _slugify(meta["name"])
+            if stype == "FILL":
+                self.style_id_to_color[sid] = slug
+                fill_sids.append(sid)
+            elif stype == "TEXT":
+                self.type_map[sid] = slug
+                text_sids.append(sid)
+
+        # Step 2: fetch style nodes directly to get actual paint/font values
+        if api and file_key and self.style_meta:
+            self._fetch_style_nodes(api, file_key, fill_sids, text_sids)
+
+        # Step 3: tree walk as fallback for any style not yet resolved
+        self._walk(document)
+
+        return {
+            "color_map": self.color_map,
+            "style_id_to_color": self.style_id_to_color,
+            "type_map": self.type_map,
+            "color_tokens": self.color_tokens,
+            "type_tokens": self.type_tokens,
+        }
+
+    def _fetch_style_nodes(
+        self, api, file_key: str, fill_sids: list[str], text_sids: list[str]
+    ) -> None:
+        # Build node_id -> style_id reverse map
+        nid_to_sid: dict[str, str] = {}
+        for sid, meta in self.style_meta.items():
+            nid = meta.get("node_id") or meta.get("nodeId", "")
+            if nid:
+                nid_to_sid[nid] = sid
+
+        all_nids = list(nid_to_sid.keys())
+        if not all_nids:
+            return
+
+        # Batch fetch — Tier 2, 50 IDs per request
+        node_docs: dict[str, dict] = {}
+        for i in range(0, len(all_nids), _NODE_BATCH):
+            batch = all_nids[i : i + _NODE_BATCH]
+            try:
+                node_docs.update(api.get_nodes(file_key, batch))
+            except Exception as exc:
+                print(f"  Warning: could not fetch style nodes batch: {exc}")
+
+        fill_set = set(fill_sids)
+        text_set = set(text_sids)
+
+        for nid, doc in node_docs.items():
+            sid = nid_to_sid.get(nid)
+            if not sid:
+                continue
+
+            if sid in fill_set:
+                slug = self.style_id_to_color.get(sid)
+                if not slug or slug in self.color_tokens:
+                    continue
+                fills = doc.get("fills", [])
+                if fills and fills[0].get("type") == "SOLID" and fills[0].get("visible", True):
+                    hex_val = rgba_to_hex(fills[0]["color"])
+                    self.color_map.setdefault(hex_val, slug)
+                    self.color_tokens[slug] = f"#{hex_val}"
+
+            elif sid in text_set:
+                slug = self.type_map.get(sid)
+                if not slug or slug in self.type_tokens:
+                    continue
+                style = doc.get("style", {})
+                if style:
+                    self.type_tokens[slug] = {
+                        "fontFamily": style.get("fontFamily"),
+                        "fontSize": style.get("fontSize"),
+                        "fontWeight": style.get("fontWeight"),
+                        "lineHeight": style.get("lineHeightPx"),
+                        "letterSpacing": style.get("letterSpacing", 0),
+                    }
+
+    def _walk(self, node: dict) -> None:
+        """Fallback: collect token values from nodes that reference named styles."""
+        styles_ref = node.get("styles", {})
+
+        # Fill style
+        fill_sid = (
+            styles_ref.get("fill")
+            or styles_ref.get("fills")
+            or node.get("fillStyleId")
+        )
+        if fill_sid and fill_sid in self.style_meta:
+            slug = self.style_id_to_color.get(fill_sid) or _slugify(self.style_meta[fill_sid]["name"])
+            self.style_id_to_color.setdefault(fill_sid, slug)
+            if slug not in self.color_tokens:
+                fills = node.get("fills", [])
+                if fills and fills[0].get("type") == "SOLID" and fills[0].get("visible", True):
+                    hex_val = rgba_to_hex(fills[0]["color"])
+                    self.color_map.setdefault(hex_val, slug)
+                    self.color_tokens[slug] = f"#{hex_val}"
+
+        # Stroke style
+        stroke_sid = (
+            styles_ref.get("stroke")
+            or styles_ref.get("strokes")
+            or node.get("strokeStyleId")
+        )
+        if stroke_sid and stroke_sid in self.style_meta:
+            slug = self.style_id_to_color.get(stroke_sid) or _slugify(self.style_meta[stroke_sid]["name"])
+            self.style_id_to_color.setdefault(stroke_sid, slug)
+            if slug not in self.color_tokens:
+                strokes = node.get("strokes", [])
+                if strokes and strokes[0].get("type") == "SOLID" and strokes[0].get("visible", True):
+                    hex_val = rgba_to_hex(strokes[0]["color"])
+                    self.color_map.setdefault(hex_val, slug)
+                    self.color_tokens[slug] = f"#{hex_val}"
+
+        # Text style
+        text_sid = styles_ref.get("text") or node.get("textStyleId")
+        if text_sid and text_sid in self.style_meta:
+            slug = self.type_map.get(text_sid) or _slugify(self.style_meta[text_sid]["name"])
+            self.type_map.setdefault(text_sid, slug)
+            if slug not in self.type_tokens:
+                style = node.get("style", {})
+                self.type_tokens[slug] = {
+                    "fontFamily": style.get("fontFamily"),
+                    "fontSize": style.get("fontSize"),
+                    "fontWeight": style.get("fontWeight"),
+                    "lineHeight": style.get("lineHeightPx"),
+                    "letterSpacing": style.get("letterSpacing", 0),
+                }
+
+        for child in node.get("children", []):
+            self._walk(child)

extrafigma/utils/color.py

@@ -0,0 +1,36 @@
+from typing import Optional
+
+
+def rgba_to_hex(color: dict) -> str:
+    """Convert Figma color dict (r,g,b as 0-1 floats) to 6-char uppercase hex."""
+    r = max(0, min(255, round(color.get("r", 0) * 255)))
+    g = max(0, min(255, round(color.get("g", 0) * 255)))
+    b = max(0, min(255, round(color.get("b", 0) * 255)))
+    return f"{r:02X}{g:02X}{b:02X}"
+
+
+def find_nearest(hex_val: str, token_map: dict, tolerance: int = 2) -> Optional[str]:
+    """Find the nearest color token within per-channel tolerance."""
+    try:
+        tr = int(hex_val[0:2], 16)
+        tg = int(hex_val[2:4], 16)
+        tb = int(hex_val[4:6], 16)
+    except (ValueError, IndexError):
+        return None
+
+    best_name: Optional[str] = None
+    best_dist = float("inf")
+
+    for candidate, name in token_map.items():
+        try:
+            cr = int(candidate[0:2], 16)
+            cg = int(candidate[2:4], 16)
+            cb = int(candidate[4:6], 16)
+        except (ValueError, IndexError):
+            continue
+        dist = max(abs(tr - cr), abs(tg - cg), abs(tb - cb))
+        if dist <= tolerance and dist < best_dist:
+            best_dist = dist
+            best_name = name
+
+    return best_name

extrafigma/utils/file_key.py

@@ -0,0 +1,18 @@
+import re
+from typing import Optional
+
+_URL_PATTERNS = [
+    r"figma\.com/(?:design|file|proto|make)/([A-Za-z0-9_-]+)",
+]
+_RAW_KEY = re.compile(r"^[A-Za-z0-9_-]{6,}$")
+
+
+def parse_file_key(url_or_key: str) -> Optional[str]:
+    url_or_key = url_or_key.strip()
+    for pattern in _URL_PATTERNS:
+        m = re.search(pattern, url_or_key)
+        if m:
+            return m.group(1)
+    if _RAW_KEY.match(url_or_key):
+        return url_or_key
+    return None

extrafigma/utils/layout.py

@@ -0,0 +1,40 @@
+_DIRECTION = {
+    "HORIZONTAL": "row",
+    "VERTICAL": "column",
+}
+
+_AXIS_ALIGN = {
+    "MIN": "flex-start",
+    "CENTER": "center",
+    "MAX": "flex-end",
+    "SPACE_BETWEEN": "space-between",
+    "BASELINE": "baseline",
+}
+
+_SIZING = {
+    "FIXED": "fixed",
+    "HUG": "hug",
+    "FILL": "fill",
+}
+
+
+def distill_layout(node: dict) -> dict:
+    mode = node.get("layoutMode", "NONE")
+    if mode == "NONE":
+        return {"mode": "absolute"}
+    return {
+        "mode": "flex",
+        "direction": _DIRECTION.get(mode, "column"),
+        "mainAxis": _AXIS_ALIGN.get(node.get("primaryAxisAlignItems", "MIN"), "flex-start"),
+        "crossAxis": _AXIS_ALIGN.get(node.get("counterAxisAlignItems", "MIN"), "flex-start"),
+        "gap": node.get("itemSpacing", 0),
+        "padding": {
+            "top": node.get("paddingTop", 0),
+            "right": node.get("paddingRight", 0),
+            "bottom": node.get("paddingBottom", 0),
+            "left": node.get("paddingLeft", 0),
+        },
+        "wrap": node.get("layoutWrap") == "WRAP",
+        "widthMode": _SIZING.get(node.get("layoutSizingHorizontal", "FIXED"), "fixed"),
+        "heightMode": _SIZING.get(node.get("layoutSizingVertical", "FIXED"), "fixed"),
+    }

extrafigma-0.1.0.dist-info/METADATA

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: extrafigma
+Version: 0.1.0
+Summary: Pull Figma files into agent-readable local folders
+Project-URL: Homepage, https://github.com/think41/extrafigma
+Project-URL: Repository, https://github.com/think41/extrafigma
+Project-URL: Issues, https://github.com/think41/extrafigma/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,cli,codegen,design,figma
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.12.0
+Description-Content-Type: text/markdown
+
+# ExtraFigma
+
+A pull-only CLI that converts Figma files into agent-readable local folders. Drop the output into your project and let Claude Code (or any AI coding agent) implement pixel-perfect frontend code from the design.
+
+## Install
+
+```bash
+pip install extrafigma
+# or
+uvx extrafigma --help
+```
+
+## Quick start
+
+```bash
+extrafigma pull "https://www.figma.com/design/abc123/My-App" ./my-design
+```
+
+On first run you'll be prompted for a Figma Personal Access Token. Get one at **Figma → Settings → Security → Personal Access Tokens** (scopes needed: `file_content:read`, `file_metadata:read`).
+
+The token is stored at `~/.config/extrafigma/credentials.json` and reused for all future pulls.
+
+## What gets extracted
+
+```
+my-design/
+  CLAUDE.md               ← instructions for AI agents
+  index.md                ← overview of all pages and frames
+  tokens/
+    colors.json           ← named color styles → hex values
+    typography.json       ← named text styles → font properties
+  assets/
+    icon-name.svg         ← exported SVG icons (VECTOR nodes)
+  pages/
+    Page-1/
+      page.md
+      Hero.frame.json     ← distilled layout tree (CSS-friendly)
+      Hero.png            ← 2× frame render (visual ground truth)
+```
+
+### `frame.json` structure
+
+Every frame is distilled to a CSS-friendly layout tree:
+
+```json
+{
+  "type": "FRAME",
+  "name": "Hero",
+  "width": 1440,
+  "height": 900,
+  "layout": { "mode": "flex", "direction": "column", "gap": 24 },
+  "background": "colors/brand-primary",
+  "borderRadius": 0,
+  "children": [
+    {
+      "type": "TEXT",
+      "content": "Welcome",
+      "style": "typography/heading-xl",
+      "color": "colors/gray-800"
+    }
+  ]
+}
+```
+
+Named Figma Styles become tokens (`colors/brand-primary`, `typography/heading-xl`). Raw hex values that weren't saved as styles are flagged with `# not in tokens`.
+
+## Auth commands
+
+```bash
+extrafigma auth login               # interactive prompt
+extrafigma auth login --pat <token> # non-interactive (CI-friendly)
+extrafigma auth status              # check stored PAT
+extrafigma auth logout              # remove stored PAT
+```
+
+## Rate limits
+
+Figma's REST API limits `GET /v1/files` calls based on your seat type:
+
+| Seat | Limit |
+|------|-------|
+| View / Collab | 6 per month |
+| Dev / Full (Starter) | 10 per minute |
+| Dev / Full (Professional) | 15 per minute |
+
+Use an account with an **editor seat** on the file for meaningful usage.
+
+## Known limitations
+
+- **Design tokens require named Figma Styles.** If the designer applied colors directly without saving them as named styles, tokens will be empty. Variables (Figma Professional+) are not supported — use Styles instead.
+- **SVG export skips remote library components.** Icons that are instances of components from external shared libraries cannot be exported via the REST API. They'll appear as `INSTANCE` nodes in the frame JSON.
+- **x/y positions** are canvas-space coordinates. For absolute-layout frames, subtract the parent's x/y to get relative positions.
+
+## How it works
+
+1. `GET /v1/files/:key` — fetches the full document tree
+2. Batch-fetches style node data to resolve exact color/font values
+3. Distills each top-level frame to a CSS-friendly JSON tree
+4. Exports frame PNGs at 2× resolution
+5. Exports VECTOR nodes as SVGs in a second pass
+
+## License
+
+MIT

extrafigma-0.1.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+extrafigma/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+extrafigma/api.py,sha256=08W_3A2chsOB04k9-4g_48RDYF2cixxQIjuIAu8H_70,3933
+extrafigma/auth.py,sha256=NuzuFYPXuYZ3m4ac1nYup6qeEP5N4Skh01c9J85NlJM,788
+extrafigma/cli.py,sha256=Z87xIrbGKnYXvmrm9_yLbMDf-8s9LaCRP-mo25aMKag,3285
+extrafigma/puller/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+extrafigma/puller/distiller.py,sha256=nf3jzDUoXMsR2_YT_gOT0opODGKjdjVAsUiub8xFxfU,7916
+extrafigma/puller/index_writer.py,sha256=HMPmuqyk0VPKU15EzHOh9MRSlkUnhgM8M_Pn9w_GgJw,1603
+extrafigma/puller/page_writer.py,sha256=1UsuwZgns46p93Vl9U8luI2OoNErrGLRdNVfVbvXITc,1148
+extrafigma/puller/pull.py,sha256=YY9KbhOVvB2gjPGcTgI07FpNyQwLkfDgFAwJB-02w9Y,7205
+extrafigma/puller/renderer.py,sha256=CZpc06QT3wWOhFSWd0VbemJJoNeaR5Zzjfs6lwFnz6I,3592
+extrafigma/puller/snapshot.py,sha256=HohJpIbY4nVShvk82UENPVJYhFojjKoeAoHwLJdgGgo,831
+extrafigma/puller/token_extractor.py,sha256=Occ9gKSOu-M0GXzyN4rwEH6L7hMz260MSVSAW9u03-g,6832
+extrafigma/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+extrafigma/utils/color.py,sha256=NjhuPbqht2zvxb4ZbnfcH3jqyUl-VW1Bl2-If9Or_iE,1187
+extrafigma/utils/file_key.py,sha256=oDAy5yUg4htaviBJtpfpme-x540mOUsXi-tbPObtoPw,458
+extrafigma/utils/layout.py,sha256=fgm9LI1Qv9S4_88KloBGqdTLdeJ7rQI3z97CNtOCp1E,1222
+extrafigma-0.1.0.dist-info/METADATA,sha256=IYgDhT3GplNYMlUJNm79SvHWgR2OIO4Y9heuiiuHen0,4280
+extrafigma-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+extrafigma-0.1.0.dist-info/entry_points.txt,sha256=oBXbCiyMPtfYY0Fhspu5l-CbTAqf0VprJA7kfK9wOkQ,50
+extrafigma-0.1.0.dist-info/licenses/LICENSE,sha256=-KeMNo2TQu_j6tdBpkf2djhjRBd5bGNULsX1YxQN0EU,1064
+extrafigma-0.1.0.dist-info/RECORD,,

extrafigma-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

extrafigma-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+extrafigma = extrafigma.cli:app

extrafigma-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Think41
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.