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

{figma_cli-0.2.0 → figma_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: figma-cli
-Version: 0.2.0
+Version: 0.3.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
@@ -49,17 +49,39 @@ The npm package `silships/figma-cli` also installs a `figma-cli` executable. If
 
 ## Usage
 
-Every command talks to the Figma REST API with a personal access token. Create one under Figma account settings and export it:
+Every command talks to the Figma REST API with a personal access token. Create one under Figma account settings (Security > Personal access tokens) with these scopes, the minimum the commands below need per [Figma's scope reference](https://developers.figma.com/docs/rest-api/scopes/):
+
+| Scope | Used by |
+| --- | --- |
+| `current_user:read` | `auth check`, `auth login` (`GET /v1/me`) |
+| `file_content:read` | `file get`, `export` |
+| `file_comments:read` | `comment list` |
+| `file_comments:write` | `comment post`, `comment delete` |
+
+Then store it once with `figma auth login`:
+
+```sh
+figma auth login                       # interactive: prints the steps, opens settings, hidden prompt
+echo "$TOKEN" | figma auth login       # agents and CI: piped stdin
+figma auth login --token - < token.txt # same, explicit
+```
+
+`auth login` validates the token against `GET /v1/me` before writing anything. A rejected token exits 3 and leaves any existing token file untouched. A valid one is written to `~/.config/figma/token` with mode `0600` (its directory `0700`), through a temporary file renamed into place, so a failed write keeps the previous token, and the command reports the authenticated `id`, `handle` and `email` plus the file path. Prefer stdin over `--token <value>`, which exposes the token in process listings and shell history. Empty stdin exits 2. Add `--no-browser` to skip opening the settings page.
+
+Alternatively, export the token. `FIGMA_TOKEN` takes precedence over the stored file whenever it is set and non-empty:
 
 ```sh
 export FIGMA_TOKEN=figd_...
 export FIGMA_API_BASE=https://api.figma.com   # optional, this is the default
 ```
 
+With neither set, commands fail with `{"error": "missing_token"}` and exit code 3.
+
 Every subcommand prints human-readable text by default and a JSON document on stdout with `--json`.
 
 | Command | Figma endpoint |
 | --- | --- |
+| `figma auth login [--token TOKEN\|-] [--no-browser]` | `GET /v1/me`, then writes `~/.config/figma/token` |
 | `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 |
@@ -161,9 +183,9 @@ 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`.
+The tests are hermetic: no network access and no Figma token are needed, and `HOME` points at a temporary directory so a stored token never leaks in. 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.
+`tests/test_live.py` runs against the real API only when `FIGMA_TOKEN` is set. With the token alone it checks `auth check` and runs `auth login` from stdin into a temporary `HOME`; the file, comment and export checks also need `FIGMA_TEST_FILE_KEY` (add `FIGMA_TEST_NODE_ID` to exercise export). The comment check 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
 

{figma_cli-0.2.0 → figma_cli-0.3.0}/README.md

@@ -24,17 +24,39 @@ The npm package `silships/figma-cli` also installs a `figma-cli` executable. If
 
 ## Usage
 
-Every command talks to the Figma REST API with a personal access token. Create one under Figma account settings and export it:
+Every command talks to the Figma REST API with a personal access token. Create one under Figma account settings (Security > Personal access tokens) with these scopes, the minimum the commands below need per [Figma's scope reference](https://developers.figma.com/docs/rest-api/scopes/):
+
+| Scope | Used by |
+| --- | --- |
+| `current_user:read` | `auth check`, `auth login` (`GET /v1/me`) |
+| `file_content:read` | `file get`, `export` |
+| `file_comments:read` | `comment list` |
+| `file_comments:write` | `comment post`, `comment delete` |
+
+Then store it once with `figma auth login`:
+
+```sh
+figma auth login                       # interactive: prints the steps, opens settings, hidden prompt
+echo "$TOKEN" | figma auth login       # agents and CI: piped stdin
+figma auth login --token - < token.txt # same, explicit
+```
+
+`auth login` validates the token against `GET /v1/me` before writing anything. A rejected token exits 3 and leaves any existing token file untouched. A valid one is written to `~/.config/figma/token` with mode `0600` (its directory `0700`), through a temporary file renamed into place, so a failed write keeps the previous token, and the command reports the authenticated `id`, `handle` and `email` plus the file path. Prefer stdin over `--token <value>`, which exposes the token in process listings and shell history. Empty stdin exits 2. Add `--no-browser` to skip opening the settings page.
+
+Alternatively, export the token. `FIGMA_TOKEN` takes precedence over the stored file whenever it is set and non-empty:
 
 ```sh
 export FIGMA_TOKEN=figd_...
 export FIGMA_API_BASE=https://api.figma.com   # optional, this is the default
 ```
 
+With neither set, commands fail with `{"error": "missing_token"}` and exit code 3.
+
 Every subcommand prints human-readable text by default and a JSON document on stdout with `--json`.
 
 | Command | Figma endpoint |
 | --- | --- |
+| `figma auth login [--token TOKEN\|-] [--no-browser]` | `GET /v1/me`, then writes `~/.config/figma/token` |
 | `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 |
@@ -136,9 +158,9 @@ 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`.
+The tests are hermetic: no network access and no Figma token are needed, and `HOME` points at a temporary directory so a stored token never leaks in. 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.
+`tests/test_live.py` runs against the real API only when `FIGMA_TOKEN` is set. With the token alone it checks `auth check` and runs `auth login` from stdin into a temporary `HOME`; the file, comment and export checks also need `FIGMA_TEST_FILE_KEY` (add `FIGMA_TEST_NODE_ID` to exercise export). The comment check 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
 

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

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

{figma_cli-0.2.0 → figma_cli-0.3.0}/src/figma_cli/cli.py

@@ -13,16 +13,17 @@ from typing import Any
 
 from figma_cli import __version__
 from figma_cli.client import FigmaClient, FigmaError, download
+from figma_cli.login import login
 
-Handler = Callable[[FigmaClient, argparse.Namespace], tuple[Any, str]]
+# Most handlers take (client, args); those marked needs_client=False take (args).
+Handler = Callable[..., 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()
+def _identity(me: dict[str, Any]) -> tuple[dict[str, Any], str]:
     ident = {key: me.get(key) for key in ("id", "handle", "email")}
     return (
         ident,
@@ -30,6 +31,16 @@ def _auth_check(client: FigmaClient, args: argparse.Namespace) -> tuple[Any, str
     )
 
 
+def _auth_check(client: FigmaClient, args: argparse.Namespace) -> tuple[Any, str]:
+    return _identity(client.me())
+
+
+def _auth_login(args: argparse.Namespace) -> tuple[Any, str]:
+    me, path = login(args)
+    ident, text = _identity(me)
+    return {**ident, "token_path": str(path)}, f"{text}\nToken saved to {path}"
+
+
 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]
@@ -125,7 +136,10 @@ def build_parser() -> argparse.ArgumentParser:
         description=(
             "Headless Figma CLI for AI coding agents and automated design inspection."
         ),
-        epilog="Environment: FIGMA_TOKEN (required), FIGMA_API_BASE (optional).",
+        epilog=(
+            "Environment: FIGMA_TOKEN (optional when 'figma auth login' has stored"
+            " ~/.config/figma/token), FIGMA_API_BASE (optional)."
+        ),
     )
     parser.add_argument(
         "--version", action="version", version=f"%(prog)s {__version__}"
@@ -134,10 +148,30 @@ def build_parser() -> argparse.ArgumentParser:
     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 = commands.add_parser("auth", help="token setup and 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 = auth_cmds.add_parser(
+        "check", parents=[common], help="validate FIGMA_TOKEN or stored token file"
+    )
     p.set_defaults(handler=_auth_check)
+    p = auth_cmds.add_parser(
+        "login",
+        parents=[common],
+        help="validate a token and store it in ~/.config/figma/token",
+    )
+    p.add_argument(
+        "--token",
+        help=(
+            "token value, or '-' to read stdin; a literal value shows in ps and"
+            " shell history, so prefer piped stdin, which is read without this flag"
+        ),
+    )
+    p.add_argument(
+        "--browser",
+        action=argparse.BooleanOptionalAction,
+        help="open Figma settings when prompting interactively (default: open)",
+    )
+    p.set_defaults(handler=_auth_login, needs_client=False)
 
     file = commands.add_parser("file", help="file inspection")
     file_cmds = file.add_subparsers(dest="action", metavar="<action>", required=True)
@@ -194,7 +228,10 @@ def main(argv: Sequence[str] | None = None) -> int:
         parser.print_help()
         return 0
     try:
-        payload, text = handler(FigmaClient.from_env(), args)
+        if getattr(args, "needs_client", True):
+            payload, text = handler(FigmaClient.from_env(), args)
+        else:
+            payload, text = handler(args)
     except FigmaError as err:
         if args.json:
             _print_json(err.payload)

{figma_cli-0.2.0 → figma_cli-0.3.0}/src/figma_cli/client.py

@@ -14,11 +14,13 @@ import time
 import urllib.error
 import urllib.parse
 import urllib.request
+from pathlib import Path
 from typing import Any
 
 DEFAULT_API_BASE = "https://api.figma.com"
 TOKEN_HEADER = "X-Figma-Token"
 TIMEOUT_SECONDS = 60
+EXIT_USAGE = 2
 EXIT_API_ERROR = 3
 
 _ERROR_NAMES = {
@@ -93,6 +95,26 @@ def _network_error(err: OSError) -> FigmaError:
     return FigmaError({"error": "network_error", "message": str(reason)})
 
 
+def token_path() -> Path:
+    """Where ``figma auth login`` stores the token: ``~/.config/figma/token``."""
+    return Path.home() / ".config" / "figma" / "token"
+
+
+def read_token_file() -> str:
+    """Return the stored token, or "" when no regular file holds one."""
+    path = token_path()
+    if not path.is_file():
+        return ""
+    try:
+        return path.read_text(encoding="utf-8").strip()
+    except (OSError, UnicodeError) as err:
+        raise FigmaError({"error": "token_unreadable", "message": str(err)}) from None
+
+
+def api_base() -> str:
+    return os.environ.get("FIGMA_API_BASE", "").strip() or DEFAULT_API_BASE
+
+
 def _quote(segment: str) -> str:
     return urllib.parse.quote(segment, safe="")
 
@@ -113,13 +135,15 @@ class FigmaClient:
 
     @classmethod
     def from_env(cls) -> "FigmaClient":
-        token = os.environ.get("FIGMA_TOKEN", "").strip()
+        """Read FIGMA_TOKEN, falling back to the stored token file."""
+        token = os.environ.get("FIGMA_TOKEN", "").strip() or read_token_file()
         if not token:
-            raise FigmaError(
-                {"error": "missing_token", "message": "FIGMA_TOKEN is not set"}
+            message = (
+                f"FIGMA_TOKEN is not set and {token_path()} holds no token;"
+                " run 'figma auth login'"
             )
-        base = os.environ.get("FIGMA_API_BASE", "").strip() or DEFAULT_API_BASE
-        return cls(token, base)
+            raise FigmaError({"error": "missing_token", "message": message})
+        return cls(token, api_base())
 
     def request(
         self,

figma_cli-0.3.0/src/figma_cli/login.py

@@ -0,0 +1,108 @@
+"""``figma auth login``: obtain a token, validate it, then store it.
+
+The token is checked against ``GET /v1/me`` before anything touches disk, so a
+rejected token never replaces a working one.
+"""
+
+import argparse
+import getpass
+import os
+import secrets
+import sys
+import webbrowser
+from pathlib import Path
+
+from figma_cli.client import EXIT_USAGE, FigmaClient, FigmaError, api_base, token_path
+
+SETTINGS_URL = "https://www.figma.com/settings"
+SCOPES = (
+    "current_user:read",
+    "file_content:read",
+    "file_comments:read",
+    "file_comments:write",
+)
+INSTRUCTIONS = f"""\
+Create a personal access token for figma-cli:
+  1. Open {SETTINGS_URL} and go to Security > Personal access tokens.
+  2. Generate a new token with these scopes:
+{chr(10).join(f"       {scope}" for scope in SCOPES)}
+  3. Paste the token below (input is hidden).
+"""
+
+
+class TokenInputError(FigmaError):
+    """A missing or malformed token on input: a usage error, exit 2."""
+
+    exit_code = EXIT_USAGE
+
+    def __init__(self, error: str, message: str):
+        super().__init__({"error": error, "message": message})
+
+
+def _prompt(open_browser: bool) -> str:
+    print(INSTRUCTIONS, file=sys.stderr)
+    if open_browser:
+        webbrowser.open(SETTINGS_URL)
+    return getpass.getpass("Figma personal access token: ")
+
+
+def candidate_token(args: argparse.Namespace) -> str:
+    """Take the token from --token, from stdin, or from a hidden prompt."""
+    if args.token is not None and args.token != "-":
+        token = args.token
+    elif args.token == "-" or not sys.stdin.isatty():
+        token = sys.stdin.read()
+    else:
+        token = _prompt(args.browser is not False)
+    token = token.strip()
+    if not token:
+        raise TokenInputError("empty_token", "no token was provided")
+    if any(not "!" <= ch <= "~" for ch in token):
+        message = "token must be visible ASCII, without spaces or line breaks"
+        raise TokenInputError("invalid_token", message)
+    return token
+
+
+def save_token(token: str) -> Path:
+    """Store the token at mode 0600, replacing any old file only once it is written.
+
+    The new file is created 0600 under a fresh name (O_EXCL, so never through a
+    planted file or symlink), then renamed over the old one: a failed write
+    leaves the previous token intact, and nothing is ever readable by others.
+    """
+    path = token_path()
+    tmp = path.with_name(f".{path.name}.{secrets.token_hex(8)}")
+    try:
+        path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+        path.parent.chmod(0o700)  # refuses a directory owned by someone else
+        fd = os.open(tmp, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as fh:
+                fh.write(token + "\n")
+                fh.flush()
+                os.fsync(fh.fileno())
+            os.replace(tmp, path)
+            try:
+                dir_fd = os.open(path.parent, os.O_RDONLY)
+                try:
+                    os.fsync(dir_fd)
+                finally:
+                    os.close(dir_fd)
+            except OSError:
+                pass
+        except BaseException:
+            tmp.unlink(missing_ok=True)
+            raise
+    except OSError as err:
+        raise FigmaError({"error": "write_failed", "message": str(err)}) from None
+    return path
+
+
+def login(args: argparse.Namespace) -> tuple[dict, Path]:
+    """Validate a candidate token, store it, and return (identity, path)."""
+    token = candidate_token(args)
+    me = FigmaClient(token, api_base()).me()
+    if not isinstance(me, dict) or not me.get("id"):
+        message = "GET /v1/me returned no user id"
+        raise FigmaError({"error": "invalid_response", "message": message})
+    return me, save_token(token)

figma_cli-0.3.0/tests/conftest.py

@@ -0,0 +1,11 @@
+import pytest
+
+
+@pytest.fixture(autouse=True)
+def home(monkeypatch, tmp_path):
+    """Point HOME at an empty directory so no test reads a real stored token."""
+    home = tmp_path / "home"
+    home.mkdir()
+    monkeypatch.setenv("HOME", str(home))
+    monkeypatch.setenv("USERPROFILE", str(home))
+    return home

{figma_cli-0.2.0 → figma_cli-0.3.0}/tests/test_cli.py

@@ -1,5 +1,6 @@
 """Hermetic tests for the CLI entrypoint: no network, no installed scripts required."""
 
+import io
 import json
 import os
 import subprocess
@@ -242,7 +243,116 @@ def test_error_human_on_stderr(stub, monkeypatch, capsys):
     assert "forbidden (HTTP 403): Invalid token" in captured.err
 
 
-def test_missing_token_exits_three(monkeypatch, capsys):
+def test_missing_token_exits_three(home, monkeypatch, capsys):
+    monkeypatch.setenv("HOME", str(home))
     monkeypatch.delenv("FIGMA_TOKEN", raising=False)
     assert main(["auth", "check", "--json"]) == 3
     assert json.loads(capsys.readouterr().out)["error"] == "missing_token"
+
+
+# auth login: token acquisition, with a stub standing in for GET /v1/me.
+
+
+class FakeStdin(io.StringIO):
+    def __init__(self, text: str = "", tty: bool = False):
+        super().__init__(text)
+        self.tty = tty
+
+    def isatty(self):
+        return self.tty
+
+
+@pytest.fixture
+def login_stub(monkeypatch):
+    """Record the token login validates with; fail if it goes through from_env."""
+    seen = []
+
+    def build(token, base):
+        seen.append((token, base))
+        return StubClient()
+
+    def no_env():
+        raise AssertionError("auth login must not call FigmaClient.from_env")
+
+    monkeypatch.setattr("figma_cli.login.FigmaClient", build)
+    monkeypatch.setattr("figma_cli.cli.FigmaClient.from_env", no_env)
+    monkeypatch.delenv("FIGMA_TOKEN", raising=False)
+    monkeypatch.delenv("FIGMA_API_BASE", raising=False)
+    return seen
+
+
+def _stored(home: Path) -> str:
+    return (home / ".config" / "figma" / "token").read_text()
+
+
+def test_login_token_flag(login_stub, home, monkeypatch, capsys):
+    monkeypatch.setattr(sys, "stdin", FakeStdin("ignored"))
+    assert main(["auth", "login", "--token", " figd_flag ", "--json"]) == 0
+    assert login_stub == [("figd_flag", "https://api.figma.com")]
+    assert _stored(home) == "figd_flag\n"
+    out = json.loads(capsys.readouterr().out)
+    assert out == {
+        "id": "1",
+        "handle": "agent",
+        "email": "a@example.com",
+        "token_path": str(home / ".config" / "figma" / "token"),
+    }
+
+
+@pytest.mark.parametrize("argv", [["--token", "-"], []])
+def test_login_reads_stdin(argv, login_stub, home, monkeypatch, capsys):
+    monkeypatch.setattr(sys, "stdin", FakeStdin("figd_piped\n"))
+    assert main(["auth", "login", *argv]) == 0
+    assert login_stub[0][0] == "figd_piped"
+    assert _stored(home) == "figd_piped\n"
+    out = capsys.readouterr().out
+    assert "Authenticated as agent <a@example.com> (1)" in out
+    assert "Token saved to" in out
+
+
+@pytest.mark.parametrize("argv", [["--token", "-"], [], ["--token", " "]])
+def test_login_empty_token_exits_two(argv, login_stub, home, monkeypatch, capsys):
+    monkeypatch.setattr(sys, "stdin", FakeStdin("  \n"))
+    assert main(["auth", "login", *argv, "--json"]) == 2
+    assert json.loads(capsys.readouterr().out)["error"] == "empty_token"
+    assert login_stub == []
+    assert not (home / ".config").exists()
+
+
+@pytest.mark.parametrize("flag, opened", [([], True), (["--no-browser"], False)])
+def test_login_interactive_prompt(flag, opened, login_stub, home, monkeypatch, capsys):
+    urls = []
+    monkeypatch.setattr(sys, "stdin", FakeStdin(tty=True))
+    monkeypatch.setattr("getpass.getpass", lambda prompt: "figd_typed")
+    monkeypatch.setattr("webbrowser.open", urls.append)
+    assert main(["auth", "login", *flag]) == 0
+    assert urls == (["https://www.figma.com/settings"] if opened else [])
+    err = capsys.readouterr().err
+    for scope in (
+        "current_user:read",
+        "file_content:read",
+        "file_comments:read",
+        "file_comments:write",
+    ):
+        assert scope in err
+    assert _stored(home) == "figd_typed\n"
+
+
+def test_login_rejected_token_writes_nothing(login_stub, home, monkeypatch, capsys):
+    payload = {"error": "forbidden", "status": 403, "message": "Invalid token"}
+    monkeypatch.setattr(StubClient, "me", _raise(payload))
+    monkeypatch.setattr(sys, "stdin", FakeStdin("figd_bad"))
+    assert main(["auth", "login", "--json"]) == 3
+    assert json.loads(capsys.readouterr().out) == payload
+    assert not (home / ".config").exists()
+
+
+@pytest.mark.parametrize(
+    "token", ["figd_a\nfigd_b", "figd_a b", "figd_\x00", "figd_\u20ac"]
+)
+def test_login_malformed_token_exits_two(token, login_stub, home, monkeypatch, capsys):
+    monkeypatch.setattr(sys, "stdin", FakeStdin(token))
+    assert main(["auth", "login", "--json"]) == 2
+    assert json.loads(capsys.readouterr().out)["error"] == "invalid_token"
+    assert login_stub == []
+    assert not (home / ".config").exists()

{figma_cli-0.2.0 → figma_cli-0.3.0}/tests/test_client.py

@@ -4,6 +4,9 @@ import email.message
 import email.utils
 import io
 import json
+import os
+import stat
+import sys
 import threading
 import urllib.error
 from collections.abc import Iterator
@@ -134,7 +137,8 @@ def test_delete_comment_accepts_empty_body():
     assert opener.requests[0].full_url.endswith("/v1/files/k/comments/42")
 
 
-def test_missing_token(monkeypatch):
+def test_missing_token(home, monkeypatch):
+    monkeypatch.setenv("HOME", str(home))
     monkeypatch.delenv("FIGMA_TOKEN", raising=False)
     with pytest.raises(FigmaError) as exc:
         FigmaClient.from_env()
@@ -241,3 +245,160 @@ def test_export_downloads_asset_without_token(monkeypatch, tmp_path, capsys):
         assert [r[1] for r in cdn_rec.requests] == ["/hop/1-2.png", "/1-2.png"]
         assert not any(_has_token(r[2]) for r in cdn_rec.requests)
         assert not any(TOKEN in json.dumps(r) for r in cdn_rec.requests)
+
+
+# Stored token: auth login against a loopback /v1/me, and the from_env fallback.
+
+ME = {"id": "123", "handle": "test", "email": "test@example.com"}
+
+
+def _token_file(home):
+    return home / ".config" / "figma" / "token"
+
+
+def _seed(home, content: bytes, mode: int = 0o600):
+    path = _token_file(home)
+    path.parent.mkdir(parents=True)
+    path.write_bytes(content)
+    path.chmod(mode)
+    return path
+
+
+def _login(monkeypatch, api: str, token: str, *argv: str) -> int:
+    monkeypatch.setenv("FIGMA_API_BASE", api)
+    monkeypatch.delenv("FIGMA_TOKEN", raising=False)
+    monkeypatch.setattr(sys, "stdin", io.StringIO(token + "\n"))
+    return main(["auth", "login", "--json", *argv])
+
+
+def test_login_first_run_stores_token_0600(home, monkeypatch, capsys):
+    with serve() as (api, rec):
+        rec.routes["/v1/me"] = (200, {}, json.dumps(ME).encode())
+        assert _login(monkeypatch, api, TOKEN) == 0
+        assert rec.requests[0][2].get(TOKEN_HEADER) == TOKEN
+    path = _token_file(home)
+    assert json.loads(capsys.readouterr().out) == {**ME, "token_path": str(path)}
+    assert path.read_text() == TOKEN + "\n"
+    assert stat.S_IMODE(os.stat(path).st_mode) == 0o600
+    assert stat.S_IMODE(os.stat(path.parent).st_mode) == 0o700
+
+
+def test_login_tightens_looser_existing_file(home, monkeypatch, capsys):
+    path = _seed(home, b"figd_old\n", mode=0o644)
+    with serve() as (api, rec):
+        rec.routes["/v1/me"] = (200, {}, json.dumps(ME).encode())
+        assert _login(monkeypatch, api, TOKEN) == 0
+    assert path.read_text() == TOKEN + "\n"
+    assert stat.S_IMODE(os.stat(path).st_mode) == 0o600
+
+
+@pytest.mark.parametrize("status", [401, 403])
+def test_login_rejected_creates_no_file(status, home, monkeypatch, capsys):
+    with serve() as (api, rec):
+        rec.routes["/v1/me"] = (status, {}, b'{"err": "Invalid token"}')
+        assert _login(monkeypatch, api, "figd_bad") == 3
+    out = json.loads(capsys.readouterr().out)
+    assert out["status"] == status
+    assert not (home / ".config").exists()
+
+
+@pytest.mark.parametrize("status", [401, 403])
+def test_login_rejected_preserves_existing_file(status, home, monkeypatch, capsys):
+    original = b"figd_working-token\n"
+    path = _seed(home, original)
+    with serve() as (api, rec):
+        rec.routes["/v1/me"] = (status, {}, b"{}")
+        assert _login(monkeypatch, api, "figd_bad") == 3
+    assert path.read_bytes() == original
+    assert stat.S_IMODE(os.stat(path).st_mode) == 0o600
+
+
+def test_login_write_failure_is_structured(home, monkeypatch, capsys):
+    (home / ".config").write_text("not a directory")
+    with serve() as (api, rec):
+        rec.routes["/v1/me"] = (200, {}, json.dumps(ME).encode())
+        assert _login(monkeypatch, api, TOKEN) == 3
+    assert json.loads(capsys.readouterr().out)["error"] == "write_failed"
+
+
+def test_check_falls_back_to_stripped_token_file(home, monkeypatch, capsys):
+    _seed(home, f"  {TOKEN}\n\n".encode())
+    monkeypatch.delenv("FIGMA_TOKEN", raising=False)
+    with serve() as (api, rec):
+        rec.routes["/v1/me"] = (200, {}, json.dumps(ME).encode())
+        monkeypatch.setenv("FIGMA_API_BASE", api)
+        assert main(["auth", "check", "--json"]) == 0
+        assert rec.requests[0][2].get(TOKEN_HEADER) == TOKEN
+    assert json.loads(capsys.readouterr().out) == ME
+
+
+def test_env_token_overrides_token_file(home, monkeypatch):
+    _seed(home, b"figd_from_file\n")
+    monkeypatch.setenv("FIGMA_TOKEN", TOKEN)
+    assert FigmaClient.from_env().token == TOKEN
+    monkeypatch.setenv("FIGMA_TOKEN", " ")
+    assert FigmaClient.from_env().token == "figd_from_file"
+
+
+def test_token_file_directory_counts_as_missing(home, monkeypatch):
+    _token_file(home).mkdir(parents=True)
+    monkeypatch.delenv("FIGMA_TOKEN", raising=False)
+    with pytest.raises(FigmaError) as exc:
+        FigmaClient.from_env()
+    assert exc.value.payload["error"] == "missing_token"
+
+
+def test_undecodable_token_file_is_structured(home, monkeypatch, capsys):
+    _seed(home, b"\xff\xfe\x00bad")
+    monkeypatch.delenv("FIGMA_TOKEN", raising=False)
+    assert main(["auth", "check", "--json"]) == 3
+    assert json.loads(capsys.readouterr().out)["error"] == "token_unreadable"
+
+
+def test_login_replaces_symlink_without_following_it(home, monkeypatch, capsys):
+    target = home / "elsewhere"
+    target.write_text("untouched\n")
+    path = _token_file(home)
+    path.parent.mkdir(parents=True)
+    path.symlink_to(target)
+    with serve() as (api, rec):
+        rec.routes["/v1/me"] = (200, {}, json.dumps(ME).encode())
+        assert _login(monkeypatch, api, TOKEN) == 0
+    assert target.read_text() == "untouched\n"
+    assert not path.is_symlink()
+    assert path.read_text() == TOKEN + "\n"
+
+
+def test_login_tightens_existing_directory(home, monkeypatch, capsys):
+    _token_file(home).parent.mkdir(parents=True, mode=0o755)
+    with serve() as (api, rec):
+        rec.routes["/v1/me"] = (200, {}, json.dumps(ME).encode())
+        assert _login(monkeypatch, api, TOKEN) == 0
+    assert stat.S_IMODE(os.stat(_token_file(home).parent).st_mode) == 0o700
+
+
+def test_login_failed_write_keeps_old_token(home, monkeypatch, capsys):
+    original = b"figd_working-token\n"
+    path = _seed(home, original)
+
+    def fail(*args):
+        raise OSError("disk full")
+
+    monkeypatch.setattr("figma_cli.login.os.replace", fail)
+    with serve() as (api, rec):
+        rec.routes["/v1/me"] = (200, {}, json.dumps(ME).encode())
+        assert _login(monkeypatch, api, TOKEN) == 3
+    assert json.loads(capsys.readouterr().out)["error"] == "write_failed"
+    assert path.read_bytes() == original
+    assert sorted(p.name for p in path.parent.iterdir()) == ["token"]
+
+
+@pytest.mark.parametrize("body", [b"{}", b"[]", b'{"handle": "x"}'])
+def test_login_without_identity_keeps_old_token(body, home, monkeypatch, capsys):
+    original = b"figd_working-token\n"
+    path = _seed(home, original)
+    with serve() as (api, rec):
+        rec.routes["/v1/me"] = (200, {}, body)
+        assert _login(monkeypatch, api, TOKEN) == 3
+    assert json.loads(capsys.readouterr().out)["error"] == "invalid_response"
+    assert path.read_bytes() == original

{figma_cli-0.2.0 → figma_cli-0.3.0}/tests/test_live.py

@@ -1,11 +1,15 @@
-"""Live Figma API checks. Skipped unless FIGMA_TOKEN and FIGMA_TEST_FILE_KEY are set.
+"""Live Figma API checks. Skipped unless FIGMA_TOKEN is set; the file, export and
+comment checks also need FIGMA_TEST_FILE_KEY.
 
 FIGMA_TEST_NODE_ID (optional) names a frame to export. The comment test posts one
 comment and deletes it again.
 """
 
+import io
 import json
 import os
+import stat
+import sys
 import time
 
 import pytest
@@ -16,9 +20,8 @@ TOKEN = os.environ.get("FIGMA_TOKEN", "").strip()
 FILE_KEY = os.environ.get("FIGMA_TEST_FILE_KEY", "").strip()
 NODE_ID = os.environ.get("FIGMA_TEST_NODE_ID", "").strip()
 
-pytestmark = pytest.mark.skipif(
-    not (TOKEN and FILE_KEY), reason="FIGMA_TOKEN and FIGMA_TEST_FILE_KEY not set"
-)
+pytestmark = pytest.mark.skipif(not TOKEN, reason="FIGMA_TOKEN not set")
+needs_file = pytest.mark.skipif(not FILE_KEY, reason="FIGMA_TEST_FILE_KEY not set")
 
 
 def _run(capsys, *argv):
@@ -41,6 +44,20 @@ def test_bogus_token_is_structured(monkeypatch, capsys):
     assert out["status"] in (401, 403)
 
 
+def test_login_then_check_from_token_file(home, monkeypatch, capsys):
+    monkeypatch.delenv("FIGMA_TOKEN")
+    monkeypatch.setattr(sys, "stdin", io.StringIO(TOKEN + "\n"))
+    code, out = _run(capsys, "auth", "login")
+    assert code == 0, out
+    path = home / ".config" / "figma" / "token"
+    assert out["token_path"] == str(path)
+    assert stat.S_IMODE(os.stat(path).st_mode) == 0o600
+    code, checked = _run(capsys, "auth", "check")
+    assert code == 0, checked
+    assert checked == {key: out[key] for key in ("id", "handle", "email")}
+
+
+@needs_file
 def test_file_get_depth_one(capsys):
     code, out = _run(capsys, "file", "get", FILE_KEY, "--depth", "1")
     assert code == 0, out
@@ -49,6 +66,7 @@ def test_file_get_depth_one(capsys):
     assert all("children" not in page for page in pages)
 
 
+@needs_file
 @pytest.mark.skipif(not NODE_ID, reason="FIGMA_TEST_NODE_ID not set")
 def test_export_png(tmp_path, capsys):
     argv = ("export", FILE_KEY, "--nodes", NODE_ID, "--output", str(tmp_path))
@@ -58,6 +76,7 @@ def test_export_png(tmp_path, capsys):
         assert fh.read(4) == b"\x89PNG"
 
 
+@needs_file
 def test_comment_round_trip(capsys):
     code, posted = _run(capsys, "comment", "post", FILE_KEY, "--message", "test")
     assert code == 0, posted