figma-cli 0.1.0__tar.gz → 0.2.0__tar.gz

figma_cli-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check .
+      - name: Format
+        run: ruff format --check .
+      - name: Test
+        run: pytest tests/
+
+  live:
+    # Runs against the real Figma API when the FIGMA_TOKEN secret is configured;
+    # the tests skip cleanly when it is absent (forks, unconfigured repos).
+    runs-on: ubuntu-latest
+    needs: test
+    env:
+      FIGMA_TOKEN: ${{ secrets.FIGMA_TOKEN }}
+      FIGMA_TEST_FILE_KEY: ${{ vars.FIGMA_TEST_FILE_KEY }}
+      FIGMA_TEST_NODE_ID: ${{ vars.FIGMA_TEST_NODE_ID }}
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+      - name: Live API tests
+        run: pytest -rs tests/test_live.py

figma_cli-0.2.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.5
+Name: figma-cli
+Version: 0.2.0
+Summary: Headless Figma CLI for AI coding agents and automated design inspection.
+Project-URL: Homepage, https://github.com/imperfect-co/figma-cli
+Project-URL: Issues, https://github.com/imperfect-co/figma-cli/issues
+Author: imperfect-co
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine>=6.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# figma-cli
+
+Headless Figma CLI for AI coding agents and automated design inspection.
+
+Requires Python 3.11 or newer. Licensed under MIT.
+
+## Commands
+
+The package installs two console scripts that run the same entrypoint:
+
+- `figma-cli`
+- `figma` (short alias)
+
+Each reports its own name in `--help` and `--version`:
+
+```console
+$ figma-cli --version
+figma-cli 0.1.0
+$ figma --version
+figma 0.1.0
+```
+
+The npm package `silships/figma-cli` also installs a `figma-cli` executable. If both are installed, whichever directory comes first on `PATH` wins. Run `command -v figma-cli` to check which one you get, or use the `figma` alias.
+
+## Usage
+
+Every command talks to the Figma REST API with a personal access token. Create one under Figma account settings and export it:
+
+```sh
+export FIGMA_TOKEN=figd_...
+export FIGMA_API_BASE=https://api.figma.com   # optional, this is the default
+```
+
+Every subcommand prints human-readable text by default and a JSON document on stdout with `--json`.
+
+| Command | Figma endpoint |
+| --- | --- |
+| `figma auth check` | `GET /v1/me` |
+| `figma file get <file_key> [--depth N]` | `GET /v1/files/{file_key}?depth=N` |
+| `figma export <file_key> --nodes <ids> [--format png\|svg] [--output DIR]` | `GET /v1/images/{file_key}`, then the asset URLs |
+| `figma comment list <file_key>` | `GET /v1/files/{file_key}/comments` |
+| `figma comment post <file_key> --message TEXT [--comment-id ID] [--node-id ID]` | `POST /v1/files/{file_key}/comments` |
+| `figma comment delete <file_key> <comment_id>` | `DELETE /v1/files/{file_key}/comments/{comment_id}` |
+
+The file key is the segment after `/design/` (or `/file/`) in a Figma URL. Node ids use the `1:2` form; a URL shows them as `node-id=1-2`.
+
+### Examples
+
+Check the token:
+
+```console
+$ figma auth check --json
+{
+  "id": "123456789",
+  "handle": "Design Bot",
+  "email": "bot@example.com"
+}
+```
+
+Inspect only the pages of a file. `--depth` is passed to Figma, so the server trims the tree before it is sent:
+
+```sh
+figma file get AbCdEf123 --depth 1
+figma file get AbCdEf123 --depth 2 --json | jq '.document.children[].name'
+```
+
+Render two frames to PNG and print where they were written. Files are named `<file_key>_<node_id>.<format>` with `:` and other unsafe characters replaced by `-`; re-exporting the same node overwrites its file:
+
+```console
+$ figma export AbCdEf123 --nodes 1:2,1:3 --output shots
+shots/AbCdEf123_1-2.png
+shots/AbCdEf123_1-3.png
+```
+
+Post a comment pinned to a frame, reply to it, list the thread, then clean up:
+
+```sh
+id=$(figma comment post AbCdEf123 --message "Spacing is off" --node-id 1:2 --json | jq -r .id)
+figma comment post AbCdEf123 --message "Fixed in the next build" --comment-id "$id"
+figma comment list AbCdEf123
+figma comment delete AbCdEf123 "$id"
+```
+
+### Errors and exit codes
+
+| Exit code | Meaning |
+| --- | --- |
+| 0 | Success |
+| 2 | Usage error (bad or missing arguments) |
+| 3 | Figma API, network, or local write failure |
+
+With `--json`, a failure prints a JSON object on stdout; without it, a one-line message goes to stderr. HTTP 401, 403, 404 and 5xx become `unauthorized`, `forbidden`, `not_found` and `server_error`:
+
+```json
+{"error": "forbidden", "status": 403, "message": "Invalid token"}
+```
+
+HTTP 429 is reported at once, never retried, so the caller decides when to try again. `retry_after` comes from the `Retry-After` header and is `null` when Figma sends none:
+
+```json
+{"error": "rate_limit_exceeded", "status": 429, "retry_after": 30}
+```
+
+### Token safety
+
+A request carrying `X-Figma-Token` follows no redirects. Any 3xx answer is refused with `{"error": "redirect_refused"}` and exit code 3 before a second request is made, so the token never reaches another host. Exported images are downloaded from the pre-signed URLs Figma returns with a separate request that carries no token; only that request follows redirects.
+
+## Installation and quick run
+
+Run on-demand without installing via [uv](https://docs.astral.sh/uv/):
+
+```sh
+uvx figma-cli --help
+uvx figma-cli auth check --json
+```
+
+Or install from [PyPI](https://pypi.org/project/figma-cli/):
+
+```sh
+pip install figma-cli
+```
+
+From a local checkout:
+
+```sh
+uvx --from . figma-cli --version
+```
+
+## Development
+
+```sh
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+ruff check .
+ruff format --check .
+pytest tests/
+```
+
+The tests are hermetic: no network access and no Figma token are needed. The redirect tests use real sockets on `127.0.0.1`.
+
+`tests/test_live.py` runs against the real API only when `FIGMA_TOKEN` and `FIGMA_TEST_FILE_KEY` are set (add `FIGMA_TEST_NODE_ID` to exercise export). It posts one comment and deletes it. CI runs it in the `live` job from the `FIGMA_TOKEN` secret and the `FIGMA_TEST_FILE_KEY` / `FIGMA_TEST_NODE_ID` repository variables, and skips it when they are absent.
+
+## Release
+
+Bump `__version__` in `src/figma_cli/__init__.py`, merge, then push a matching tag (`v0.1.0` for `0.1.0`). The release workflow refuses a tag that does not match `__version__`, builds the sdist and wheel, runs `twine check`, and publishes to PyPI through trusted publishing (OIDC, the `pypi` environment).
+
+## License
+
+MIT, see [LICENSE](LICENSE).

figma_cli-0.2.0/README.md

@@ -0,0 +1,149 @@
+# figma-cli
+
+Headless Figma CLI for AI coding agents and automated design inspection.
+
+Requires Python 3.11 or newer. Licensed under MIT.
+
+## Commands
+
+The package installs two console scripts that run the same entrypoint:
+
+- `figma-cli`
+- `figma` (short alias)
+
+Each reports its own name in `--help` and `--version`:
+
+```console
+$ figma-cli --version
+figma-cli 0.1.0
+$ figma --version
+figma 0.1.0
+```
+
+The npm package `silships/figma-cli` also installs a `figma-cli` executable. If both are installed, whichever directory comes first on `PATH` wins. Run `command -v figma-cli` to check which one you get, or use the `figma` alias.
+
+## Usage
+
+Every command talks to the Figma REST API with a personal access token. Create one under Figma account settings and export it:
+
+```sh
+export FIGMA_TOKEN=figd_...
+export FIGMA_API_BASE=https://api.figma.com   # optional, this is the default
+```
+
+Every subcommand prints human-readable text by default and a JSON document on stdout with `--json`.
+
+| Command | Figma endpoint |
+| --- | --- |
+| `figma auth check` | `GET /v1/me` |
+| `figma file get <file_key> [--depth N]` | `GET /v1/files/{file_key}?depth=N` |
+| `figma export <file_key> --nodes <ids> [--format png\|svg] [--output DIR]` | `GET /v1/images/{file_key}`, then the asset URLs |
+| `figma comment list <file_key>` | `GET /v1/files/{file_key}/comments` |
+| `figma comment post <file_key> --message TEXT [--comment-id ID] [--node-id ID]` | `POST /v1/files/{file_key}/comments` |
+| `figma comment delete <file_key> <comment_id>` | `DELETE /v1/files/{file_key}/comments/{comment_id}` |
+
+The file key is the segment after `/design/` (or `/file/`) in a Figma URL. Node ids use the `1:2` form; a URL shows them as `node-id=1-2`.
+
+### Examples
+
+Check the token:
+
+```console
+$ figma auth check --json
+{
+  "id": "123456789",
+  "handle": "Design Bot",
+  "email": "bot@example.com"
+}
+```
+
+Inspect only the pages of a file. `--depth` is passed to Figma, so the server trims the tree before it is sent:
+
+```sh
+figma file get AbCdEf123 --depth 1
+figma file get AbCdEf123 --depth 2 --json | jq '.document.children[].name'
+```
+
+Render two frames to PNG and print where they were written. Files are named `<file_key>_<node_id>.<format>` with `:` and other unsafe characters replaced by `-`; re-exporting the same node overwrites its file:
+
+```console
+$ figma export AbCdEf123 --nodes 1:2,1:3 --output shots
+shots/AbCdEf123_1-2.png
+shots/AbCdEf123_1-3.png
+```
+
+Post a comment pinned to a frame, reply to it, list the thread, then clean up:
+
+```sh
+id=$(figma comment post AbCdEf123 --message "Spacing is off" --node-id 1:2 --json | jq -r .id)
+figma comment post AbCdEf123 --message "Fixed in the next build" --comment-id "$id"
+figma comment list AbCdEf123
+figma comment delete AbCdEf123 "$id"
+```
+
+### Errors and exit codes
+
+| Exit code | Meaning |
+| --- | --- |
+| 0 | Success |
+| 2 | Usage error (bad or missing arguments) |
+| 3 | Figma API, network, or local write failure |
+
+With `--json`, a failure prints a JSON object on stdout; without it, a one-line message goes to stderr. HTTP 401, 403, 404 and 5xx become `unauthorized`, `forbidden`, `not_found` and `server_error`:
+
+```json
+{"error": "forbidden", "status": 403, "message": "Invalid token"}
+```
+
+HTTP 429 is reported at once, never retried, so the caller decides when to try again. `retry_after` comes from the `Retry-After` header and is `null` when Figma sends none:
+
+```json
+{"error": "rate_limit_exceeded", "status": 429, "retry_after": 30}
+```
+
+### Token safety
+
+A request carrying `X-Figma-Token` follows no redirects. Any 3xx answer is refused with `{"error": "redirect_refused"}` and exit code 3 before a second request is made, so the token never reaches another host. Exported images are downloaded from the pre-signed URLs Figma returns with a separate request that carries no token; only that request follows redirects.
+
+## Installation and quick run
+
+Run on-demand without installing via [uv](https://docs.astral.sh/uv/):
+
+```sh
+uvx figma-cli --help
+uvx figma-cli auth check --json
+```
+
+Or install from [PyPI](https://pypi.org/project/figma-cli/):
+
+```sh
+pip install figma-cli
+```
+
+From a local checkout:
+
+```sh
+uvx --from . figma-cli --version
+```
+
+## Development
+
+```sh
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+ruff check .
+ruff format --check .
+pytest tests/
+```
+
+The tests are hermetic: no network access and no Figma token are needed. The redirect tests use real sockets on `127.0.0.1`.
+
+`tests/test_live.py` runs against the real API only when `FIGMA_TOKEN` and `FIGMA_TEST_FILE_KEY` are set (add `FIGMA_TEST_NODE_ID` to exercise export). It posts one comment and deletes it. CI runs it in the `live` job from the `FIGMA_TOKEN` secret and the `FIGMA_TEST_FILE_KEY` / `FIGMA_TEST_NODE_ID` repository variables, and skips it when they are absent.
+
+## Release
+
+Bump `__version__` in `src/figma_cli/__init__.py`, merge, then push a matching tag (`v0.1.0` for `0.1.0`). The release workflow refuses a tag that does not match `__version__`, builds the sdist and wheel, runs `twine check`, and publishes to PyPI through trusted publishing (OIDC, the `pypi` environment).
+
+## License
+
+MIT, see [LICENSE](LICENSE).

{figma_cli-0.1.0 → figma_cli-0.2.0}/src/figma_cli/__init__.py

@@ -1,3 +1,3 @@
 """Headless Figma CLI for AI coding agents and automated design inspection."""
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"

figma_cli-0.2.0/src/figma_cli/cli.py

@@ -0,0 +1,212 @@
+"""Console entrypoint shared by the ``figma-cli`` and ``figma`` commands.
+
+Exit codes: 0 success, 2 usage error, 3 Figma API, network or local write failure.
+"""
+
+import argparse
+import json
+import re
+import sys
+from collections.abc import Callable, Sequence
+from pathlib import Path
+from typing import Any
+
+from figma_cli import __version__
+from figma_cli.client import FigmaClient, FigmaError, download
+
+Handler = Callable[[FigmaClient, argparse.Namespace], tuple[Any, str]]
+
+
+def _print_json(payload: Any) -> None:
+    print(json.dumps(payload, indent=2, ensure_ascii=False))
+
+
+def _auth_check(client: FigmaClient, args: argparse.Namespace) -> tuple[Any, str]:
+    me = client.me()
+    ident = {key: me.get(key) for key in ("id", "handle", "email")}
+    return (
+        ident,
+        f"Authenticated as {ident['handle']} <{ident['email']}> ({ident['id']})",
+    )
+
+
+def _tree_lines(node: dict[str, Any], indent: int = 0) -> list[str]:
+    label = f"{node.get('type', '?')} {node.get('name', '')} ({node.get('id', '')})"
+    lines = ["  " * indent + label]
+    for child in node.get("children") or []:
+        lines.extend(_tree_lines(child, indent + 1))
+    return lines
+
+
+def _file_get(client: FigmaClient, args: argparse.Namespace) -> tuple[Any, str]:
+    data = client.get_file(args.file_key, args.depth)
+    header = f"{data.get('name', '')} (last modified {data.get('lastModified', '?')})"
+    tree = _tree_lines(data["document"]) if data.get("document") else []
+    return data, "\n".join([header, *tree])
+
+
+def _safe_name(node_id: str) -> str:
+    return re.sub(r"[^A-Za-z0-9_.-]", "-", node_id)
+
+
+def _export(client: FigmaClient, args: argparse.Namespace) -> tuple[Any, str]:
+    node_ids = args.nodes
+    images = client.get_images(args.file_key, node_ids, args.format)
+    missing = [n for n in node_ids if not images.get(n)]
+    if missing:
+        raise FigmaError(
+            {
+                "error": "render_failed",
+                "message": "no image URL returned",
+                "nodes": missing,
+            }
+        )
+    out_dir = Path(args.output)
+    files = []
+    for node_id in node_ids:
+        payload = download(images[node_id])
+        path = (
+            out_dir / f"{_safe_name(args.file_key)}_{_safe_name(node_id)}.{args.format}"
+        )
+        try:
+            out_dir.mkdir(parents=True, exist_ok=True)
+            path.write_bytes(payload)
+        except OSError as err:
+            raise FigmaError({"error": "write_failed", "message": str(err)}) from None
+        files.append({"node_id": node_id, "path": str(path), "bytes": len(payload)})
+    return {"files": files}, "\n".join(f["path"] for f in files)
+
+
+def _comment_line(c: dict[str, Any]) -> str:
+    user = (c.get("user") or {}).get("handle", "?")
+    reply = f" (reply to {c['parent_id']})" if c.get("parent_id") else ""
+    head = f"{c.get('id')}  {c.get('created_at', '')}  {user}{reply}"
+    return f"{head}: {c.get('message', '')}"
+
+
+def _comment_list(client: FigmaClient, args: argparse.Namespace) -> tuple[Any, str]:
+    data = client.list_comments(args.file_key)
+    lines = [_comment_line(c) for c in data.get("comments") or []]
+    return data, "\n".join(lines) or "No comments."
+
+
+def _comment_post(client: FigmaClient, args: argparse.Namespace) -> tuple[Any, str]:
+    data = client.post_comment(
+        args.file_key, args.message, comment_id=args.comment_id, node_id=args.node_id
+    )
+    return data, f"Posted comment {data.get('id')}"
+
+
+def _comment_delete(client: FigmaClient, args: argparse.Namespace) -> tuple[Any, str]:
+    client.delete_comment(args.file_key, args.comment_id)
+    return {
+        "deleted": True,
+        "id": args.comment_id,
+    }, f"Deleted comment {args.comment_id}"
+
+
+def _positive_int(value: str) -> int:
+    number = int(value)
+    if number < 1:
+        raise argparse.ArgumentTypeError("must be a positive integer")
+    return number
+
+
+def _node_list(value: str) -> list[str]:
+    nodes = [n.strip() for n in value.split(",") if n.strip()]
+    if not nodes:
+        raise argparse.ArgumentTypeError("expected one or more node ids")
+    return nodes
+
+
+def build_parser() -> argparse.ArgumentParser:
+    # prog is left unset so it follows sys.argv[0]: each alias reports its own name.
+    parser = argparse.ArgumentParser(
+        description=(
+            "Headless Figma CLI for AI coding agents and automated design inspection."
+        ),
+        epilog="Environment: FIGMA_TOKEN (required), FIGMA_API_BASE (optional).",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"%(prog)s {__version__}"
+    )
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--json", action="store_true", help="print structured JSON")
+    commands = parser.add_subparsers(dest="command", metavar="<command>")
+
+    auth = commands.add_parser("auth", help="token checks")
+    auth_cmds = auth.add_subparsers(dest="action", metavar="<action>", required=True)
+    p = auth_cmds.add_parser("check", parents=[common], help="validate FIGMA_TOKEN")
+    p.set_defaults(handler=_auth_check)
+
+    file = commands.add_parser("file", help="file inspection")
+    file_cmds = file.add_subparsers(dest="action", metavar="<action>", required=True)
+    p = file_cmds.add_parser("get", parents=[common], help="fetch the node tree")
+    p.add_argument("file_key")
+    p.add_argument("--depth", type=_positive_int, help="server-side tree depth")
+    p.set_defaults(handler=_file_get)
+
+    p = commands.add_parser("export", parents=[common], help="render nodes to files")
+    p.add_argument("file_key")
+    p.add_argument(
+        "--nodes", required=True, type=_node_list, help="comma-separated node ids"
+    )
+    p.add_argument("--format", choices=("png", "svg"), default="png")
+    p.add_argument("--output", default=".", help="destination directory")
+    p.set_defaults(handler=_export)
+
+    comment = commands.add_parser("comment", help="file comments")
+    comment_cmds = comment.add_subparsers(
+        dest="action", metavar="<action>", required=True
+    )
+    p = comment_cmds.add_parser("list", parents=[common], help="list comments")
+    p.add_argument("file_key")
+    p.set_defaults(handler=_comment_list)
+    p = comment_cmds.add_parser("post", parents=[common], help="post a comment")
+    p.add_argument("file_key")
+    p.add_argument("--message", required=True)
+    p.add_argument("--comment-id", help="reply to this comment thread")
+    p.add_argument("--node-id", help="anchor the comment to this node")
+    p.set_defaults(handler=_comment_post)
+    p = comment_cmds.add_parser("delete", parents=[common], help="delete a comment")
+    p.add_argument("file_key")
+    p.add_argument("comment_id")
+    p.set_defaults(handler=_comment_delete)
+    return parser
+
+
+def _describe(error: dict[str, Any]) -> str:
+    text = error["error"]
+    if "status" in error:
+        text += f" (HTTP {error['status']})"
+    if error.get("message"):
+        text += f": {error['message']}"
+    if error.get("retry_after") is not None:
+        text += f", retry after {error['retry_after']}s"
+    return text
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    handler: Handler | None = getattr(args, "handler", None)
+    if handler is None:
+        parser.print_help()
+        return 0
+    try:
+        payload, text = handler(FigmaClient.from_env(), args)
+    except FigmaError as err:
+        if args.json:
+            _print_json(err.payload)
+        else:
+            print(f"{parser.prog}: error: {_describe(err.payload)}", file=sys.stderr)
+        return err.exit_code
+    if args.json:
+        _print_json(payload)
+    else:
+        print(text)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())