figma-cli 0.1.0__tar.gz

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

@@ -0,0 +1,30 @@
+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/

figma_cli-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,49 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - name: Install build tools
+        run: python -m pip install build "twine>=6.1.0"
+      - name: Verify tag matches __version__
+        run: |
+          version=$(python -c "import re, pathlib; print(re.search(r'^__version__ = \"([^\"]+)\"', pathlib.Path('src/figma_cli/__init__.py').read_text(), re.M).group(1))")
+          if [ "${GITHUB_REF_NAME#v}" != "$version" ]; then
+            echo "::error::tag $GITHUB_REF_NAME does not match __version__ $version"
+            exit 1
+          fi
+      - name: Build
+        run: python -m build
+      - name: Check
+        run: twine check --strict dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/figma-cli
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

figma_cli-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+build/
+dist/
+*.egg-info/
+__pycache__/
+.venv/
+.pytest_cache/
+.ruff_cache/
+tmp/

figma_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 imperfect-co
+
+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.

figma_cli-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.5
+Name: figma-cli
+Version: 0.1.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.
+
+## Run without installing
+
+Before the first PyPI release, run straight from the repository with [uv](https://docs.astral.sh/uv/):
+
+```sh
+uvx --from git+https://github.com/imperfect-co/figma-cli figma-cli --help
+```
+
+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.
+
+## 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/README.md

@@ -0,0 +1,57 @@
+# 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.
+
+## Run without installing
+
+Before the first PyPI release, run straight from the repository with [uv](https://docs.astral.sh/uv/):
+
+```sh
+uvx --from git+https://github.com/imperfect-co/figma-cli figma-cli --help
+```
+
+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.
+
+## 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/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "figma-cli"
+dynamic = ["version"]
+description = "Headless Figma CLI for AI coding agents and automated design inspection."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [{ name = "imperfect-co" }]
+classifiers = [
+    "Environment :: Console",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest", "ruff", "build", "twine>=6.1.0"]
+
+[project.scripts]
+figma-cli = "figma_cli.cli:main"
+figma = "figma_cli.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/imperfect-co/figma-cli"
+Issues = "https://github.com/imperfect-co/figma-cli/issues"
+
+[tool.hatch.version]
+path = "src/figma_cli/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/figma_cli"]
+
+[tool.ruff]
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

figma_cli-0.1.0/src/figma_cli/__init__.py

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

figma_cli-0.1.0/src/figma_cli/cli.py

@@ -0,0 +1,28 @@
+"""Console entrypoint shared by the ``figma-cli`` and ``figma`` commands."""
+
+import argparse
+from collections.abc import Sequence
+
+from figma_cli import __version__
+
+
+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."
+        ),
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"%(prog)s {__version__}"
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    build_parser().parse_args(argv)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

figma_cli-0.1.0/tests/test_cli.py

@@ -0,0 +1,82 @@
+"""Hermetic tests for the CLI entrypoint: no network, no installed scripts required."""
+
+import os
+import subprocess
+import sys
+import tomllib
+from importlib import import_module
+from pathlib import Path
+
+import pytest
+
+from figma_cli import __version__
+from figma_cli.cli import main
+
+ROOT = Path(__file__).resolve().parent.parent
+ALIASES = ("figma-cli", "figma")
+
+
+def _scripts() -> dict[str, str]:
+    with (ROOT / "pyproject.toml").open("rb") as fh:
+        return tomllib.load(fh)["project"]["scripts"]
+
+
+def _resolve(target: str):
+    module, _, attr = target.partition(":")
+    return getattr(import_module(module), attr)
+
+
+def test_version_flag(capsys):
+    with pytest.raises(SystemExit) as exc:
+        main(["--version"])
+    assert exc.value.code == 0
+    assert __version__ in capsys.readouterr().out
+
+
+def test_help_flag(capsys):
+    with pytest.raises(SystemExit) as exc:
+        main(["--help"])
+    assert exc.value.code == 0
+    out = capsys.readouterr().out
+    assert "usage:" in out
+    assert "--version" in out
+
+
+def test_no_args_exits_zero():
+    assert main([]) == 0
+
+
+def test_unknown_flag_exits_two(capsys):
+    with pytest.raises(SystemExit) as exc:
+        main(["--no-such-flag"])
+    assert exc.value.code == 2
+    assert "unrecognized arguments" in capsys.readouterr().err
+
+
+def test_both_aliases_declared():
+    assert {name: _scripts().get(name) for name in ALIASES} == {
+        name: "figma_cli.cli:main" for name in ALIASES
+    }
+
+
+@pytest.mark.parametrize("alias", ALIASES)
+def test_alias_reports_its_own_name(alias, monkeypatch, capsys):
+    monkeypatch.setattr(sys, "argv", [alias, "--version"])
+    with pytest.raises(SystemExit) as exc:
+        _resolve(_scripts()[alias])()
+    assert exc.value.code == 0
+    assert capsys.readouterr().out.strip() == f"{alias} {__version__}"
+
+
+@pytest.mark.parametrize("flag", ["--version", "--help"])
+def test_module_execution(flag):
+    env = {**os.environ, "PYTHONPATH": str(ROOT / "src")}
+    result = subprocess.run(
+        [sys.executable, "-m", "figma_cli.cli", flag],
+        capture_output=True,
+        text=True,
+        env=env,
+        check=False,
+    )
+    assert result.returncode == 0, result.stderr
+    assert (__version__ if flag == "--version" else "usage:") in result.stdout