penpot-local-stack 0.1.0__py3-none-any.whl

penpot_local_stack-0.1.0.dist-info/METADATA

@@ -0,0 +1,180 @@
+Metadata-Version: 2.5
+Name: penpot-local-stack
+Version: 0.1.0
+Summary: A disposable local Penpot stack: import a template, draw, export it back
+Project-URL: Repository, https://github.com/oberon-systems/penpot-local-stack
+Project-URL: Issues, https://github.com/oberon-systems/penpot-local-stack/issues
+Author-email: zombig <me@zombig.name>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic-settings>=2.4
+Requires-Dist: pydantic>=2
+Requires-Dist: pyyaml>=6
+Requires-Dist: questionary>=2
+Description-Content-Type: text/markdown
+
+# penpot-local-stack
+
+A disposable [Penpot](https://penpot.app) stack for drawing UI mockups, built
+for AI-driven UI/UX work. Penpot itself is open source; its code is at
+[penpot/penpot](https://github.com/penpot/penpot).
+
+The stack exists so a design session leaves nothing behind but the drawing.
+It runs from a Compose file with no persistent state: the database lives in
+tmpfs and goes away with the containers, the profile is created on every
+start, and the only thing that survives is `templates/` in your directory.
+Mockups are stored there as unpacked Penpot exports, JSON plus SVG, so git
+shows readable diffs and an agent can read a mockup directly instead of
+looking at a picture of it.
+
+- [Install](#install)
+- [Settings](#settings)
+- [Design loop](#design-loop)
+- [Commands](#commands)
+- [Templates](#templates)
+- [Connect Penpot MCP](#connect-penpot-mcp)
+
+## Install
+
+Docker with the Compose plugin and Python 3.12 or newer have to be there
+already, and that `python3` needs `httpx`, `questionary`, `pydantic-settings`
+and `PyYAML`. The installer checks and tells you what is missing; it never
+installs anything itself.
+
+Run it in the directory that will hold the mockups:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/oberon-systems/penpot-local-stack/main/install/install.sh | bash
+```
+
+It downloads the stack and lays it out:
+
+```text
+bin/ libs/ config/   the stack, run by the system python3
+.penpot.yaml         settings, read from the directory you run in
+Makefile             up, down, import, export, extract, convert
+templates/           unpacked Penpot exports, empty at first
+```
+
+Re-running it replaces `bin/`, `libs/` and `config/`, which is the upgrade,
+and keeps `.penpot.yaml` and `templates/`. `--ref` unfolds a branch or a tag
+instead of `main`. See [install/README.md](install/README.md) for the details.
+
+## Settings
+
+The installer copies `.penpot.yaml.example` from the repository to
+`.penpot.yaml` next to the `Makefile`, and every command reads that file from
+the directory it runs in:
+
+```yaml
+templates: templates
+host: 127.0.0.1
+port: 9001
+project: penpot-local
+version: 2.17.2
+```
+
+| Key         | Default                | What it sets                    |
+| ----------- | ---------------------- | ------------------------------- |
+| `templates` | `templates`            | Where the unpacked exports live |
+| `host`      | `127.0.0.1`            | The address Penpot binds to     |
+| `port`      | `9001`                 | The port Penpot binds to        |
+| `project`   | `penpot-local`         | The Compose project name        |
+| `version`   | `2.17.2`               | The Penpot image tag            |
+| `email`     | `designer@example.com` | The throwaway profile           |
+| `password`  | `penpot-local`         | Its password                    |
+
+Drop a key to fall back to its default. Every key also answers to an
+environment variable with a `PENPOT_` prefix, and the variable wins over the
+file:
+
+```bash
+PENPOT_PORT=9100 make up
+```
+
+## Design loop
+
+Start the stack and pick a template or `(empty)`:
+
+```bash
+make up
+```
+
+`up` creates a throwaway profile and opens the browser already logged in
+through the printed `/autologin` link. If that session is lost, log in as
+`designer@example.com` with the password `penpot-local`.
+
+Draw in the browser at `http://localhost:9001`, or wherever `port` points. When you are done, pick the
+file to export and the template to write it to, then let the stack go down:
+
+```bash
+make down
+```
+
+`down` writes the export into `templates/<name>/` and runs
+`docker compose down -v`, which drops the database and the assets. Pick
+`(skip export)` to throw the work away; the wipe is confirmed first whenever
+the stack still holds a file.
+
+## Commands
+
+| Target         | What it does                                              |
+| -------------- | --------------------------------------------------------- |
+| `make up`      | Start the stack, import a template, open the browser      |
+| `make down`    | Offer the export, confirm the wipe, stop the stack        |
+| `make import`  | Import a template into the running stack, after a confirm |
+| `make export`  | Export a file into `templates/`, after a confirm          |
+| `make extract` | Unpack a `.penpot` file into `templates/`                 |
+| `make convert` | Pack a template into a `.penpot` file                     |
+
+`import` and `export` work against a running stack, so a template can be
+swapped in or a file saved off without ending the session. Both ask before
+they touch anything: `import` names the template it is about to load, `export`
+says whether it writes a new template or overwrites one that is already there.
+
+`extract` and `convert` are the offline pair and need no stack at all.
+`extract` lists the `.penpot` files next to you, asks which template to write
+and unpacks the archive under the same rules as `export`: frame thumbnails are
+dropped, JSON is reformatted, and an archive holding raster images is refused
+with the offending files listed. `convert` goes the other way and packs
+`templates/<name>/` into `<name>.penpot`, which is what you hand to a Penpot
+that is not this one. Both confirm before writing, and say whether they are
+creating something or overwriting it.
+
+## Templates
+
+- One directory per template: `manifest.json`, `files/` and `objects/`.
+- Templates are read from `templates/` in the current directory. Set
+  `PENPOT_TEMPLATES` to read them from somewhere else.
+- Images and icons must be SVG. An export that holds raster images is refused
+  and the offending files are listed, so you can replace them and export
+  again.
+- Frame thumbnails are raster renders Penpot rebuilds on its own, so the
+  export leaves them out.
+- Import keeps the Penpot file id, so a round trip changes only what you drew.
+
+## Connect Penpot MCP
+
+`up` enables MCP for the throwaway profile, issues its key and serves it
+behind the fixed `/mcp/claude` URL, so an agent needs the server added only
+once. Add it, then restart the agent:
+
+```bash
+claude mcp add --transport http penpot http://localhost:9001/mcp/claude
+```
+
+After later `up` runs, reconnect `penpot` from `/mcp` instead of restarting.
+While the stack is down, the server just shows as failed.
+
+The MCP plugin runs inside the Penpot browser tab. Keep a file open in the
+workspace while the agent works; a hidden or unloaded tab stops MCP.

penpot_local_stack-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+penpot_stack/config/autologin.conf,sha256=fchV08GGfPkhbXLIX4opQWYnrkGNZTg1hi0f0bfPP0I,154
+penpot_stack/config/compose.yaml,sha256=gvOV6yJmkmvsW-WXhRrSrm9_1YyiZqcZbVbLwW9VE_I,2358
+penpot_stack/__init__.py,sha256=mvRPyADrJna3E_OHJ8kUrIIgt1jcXgn_ZVS2sn0nzh0,87
+penpot_stack/cli.py,sha256=RUUO1wv1zMNZl2Tri0XD0VDHYTvvVxdeOnTAkUyFQ6A,4070
+penpot_stack/compose.py,sha256=oqG1fMgp2Qury_El0XYLaI7VUAjJpQt4GsZPkpDtkN0,1510
+penpot_stack/penpot.py,sha256=eDURPbFXciJz8WFwhN6PJfnktWPt2VueZnUR959brcI,2869
+penpot_stack/prompts.py,sha256=TG1buuhVaZjlySse8Kq3WbufhBuKvpnY2jzr2Snp3Ww,935
+penpot_stack/settings.py,sha256=2r1zD2SZC5CxGwvEbVPzRNTfeYjpXr0Zjs6msqfAeNQ,1456
+penpot_stack/templates.py,sha256=fMSRFINaCqJ8jhgYGvEfxeKaJ54mrcHJpj5eba9hKs4,3079
+penpot_local_stack-0.1.0.dist-info/METADATA,sha256=nyW3ujYqw97TlvDmXyZmvz04D0M_Jmi_q34YjCeOZZ8,7322
+penpot_local_stack-0.1.0.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
+penpot_local_stack-0.1.0.dist-info/entry_points.txt,sha256=V41xUQgSPhMykV3mKO1DHMga7qDBRCuYYIpj0gee36Q,55
+penpot_local_stack-0.1.0.dist-info/licenses/LICENSE,sha256=UH3T6qSdLRq_gdfrPiuNx22uO5I8kRBp8NIKGwzLKuQ,1071
+penpot_local_stack-0.1.0.dist-info/RECORD,,

penpot_local_stack-0.1.0.dist-info/WHEEL

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

penpot_local_stack-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+penpot-stack = penpot_stack.cli:main

penpot_local_stack-0.1.0.dist-info/licenses/LICENSE

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

penpot_stack/__init__.py

@@ -0,0 +1 @@
+"""Disposable Penpot stack for UI mockups: import a template, draw, export it back."""

penpot_stack/cli.py

@@ -0,0 +1,135 @@
+"""The four commands the stack exposes: up, down, import and export."""
+
+import sys
+import webbrowser
+import zipfile
+from pathlib import Path
+
+import httpx
+import questionary
+
+from . import prompts
+from .compose import compose, publish
+from .penpot import connect, drafts, files, profile, register, rpc, session
+from .settings import settings
+from .templates import archives, load, names, pack, root, save, unpack
+
+
+def choices(client: httpx.Client) -> list[questionary.Choice]:
+    return [questionary.Choice(label, value=value) for label, value in files(client)]
+
+
+def write(client: httpx.Client, file_id: str) -> bool:
+    name = prompts.target(names())
+    if name is None:
+        return False
+    target = root() / name
+    known = "Overwrite" if target.exists() else "Export to"
+    if not prompts.confirm(f"{known} templates/{name}?"):
+        return False
+    save(client, file_id, target)
+    print(f"exported to {target}")
+    return True
+
+
+def up() -> None:
+    template = prompts.source(names(), extra=[prompts.EMPTY])
+    if template is None:
+        return
+    compose("up", "-d", "--wait")
+    url = settings().url
+    client = connect(wait=300)
+    if client is None:
+        sys.exit(f"penpot is not answering on {url}")
+    publish(register(client))
+    if template != prompts.EMPTY:
+        load(client, drafts(client), root() / template)
+    login = f"{url}/autologin?token={client.cookies['auth-token']}"
+    webbrowser.open(login)
+    print(f"\nPenpot: {login}")
+    print(f"MCP:    {url}/mcp/claude")
+
+
+def down() -> None:
+    client = connect(wait=0)
+    if client is not None:
+        rpc(client, "login-with-password", **profile())
+        stored = choices(client)
+        if stored:
+            file_id = prompts.select("Export file", [prompts.SKIP, *stored])
+            if file_id is None:
+                return
+            if file_id != prompts.SKIP and not write(client, file_id):
+                return
+            if not prompts.confirm("Drop the stack and everything left in it?"):
+                return
+    compose("down", "-v")
+
+
+def export() -> None:
+    client = session()
+    stored = choices(client)
+    if not stored:
+        sys.exit("the stack holds no files to export")
+    file_id = prompts.select("Export file", stored)
+    if file_id is not None:
+        write(client, file_id)
+
+
+def restore() -> None:
+    available = names()
+    if not available:
+        sys.exit(f"no templates in {root()} to import")
+    name = prompts.source(available)
+    if name is None or not prompts.confirm(f"Import {name} into the stack?"):
+        return
+    client = session()
+    load(client, drafts(client), root() / name)
+    print(f"imported {name}")
+
+
+def extract() -> None:
+    found = archives()
+    if not found:
+        sys.exit("no .penpot files in the current directory")
+    source = prompts.select("Penpot file", [questionary.Choice(p.name, value=p) for p in found])
+    if source is None:
+        return
+    name = prompts.target(names())
+    if name is None:
+        return
+    target = root() / name
+    known = "Overwrite" if target.exists() else "Extract into"
+    if not prompts.confirm(f"{known} templates/{name}?"):
+        return
+    unpack(zipfile.ZipFile(source), target)
+    print(f"extracted to {target}")
+
+
+def convert() -> None:
+    available = names()
+    if not available:
+        sys.exit(f"no templates in {root()} to convert")
+    name = prompts.source(available)
+    if name is None:
+        return
+    target = Path.cwd() / f"{name}.penpot"
+    known = "Overwrite" if target.exists() else "Write"
+    if not prompts.confirm(f"{known} {target.name}?"):
+        return
+    target.write_bytes(pack(root() / name))
+    print(f"packed into {target}")
+
+
+def main() -> None:
+    commands = {
+        "up": up,
+        "down": down,
+        "import": restore,
+        "export": export,
+        "extract": extract,
+        "convert": convert,
+    }
+    if len(sys.argv) != 2 or sys.argv[1] not in commands:
+        sys.exit(f"usage: {Path(sys.argv[0]).name} {{{'|'.join(commands)}}}")
+    commands[sys.argv[1]]()

penpot_stack/compose.py

@@ -0,0 +1,45 @@
+"""The shipped Compose definition and the nginx route that publishes MCP."""
+
+import os
+import secrets
+import subprocess
+from pathlib import Path
+
+from .settings import Settings, settings
+
+
+def directory() -> Path:
+    here = Path(__file__).resolve().parent
+    # Installed, the stack files sit inside the package; in a checkout they are next to libs/.
+    roots = (here / "config", here.parent / "config")
+    return next(p for p in roots if (p / "compose.yaml").is_file())
+
+
+def environment(config: Settings) -> dict[str, str]:
+    return {
+        "PENPOT_PROJECT": config.project,
+        "PENPOT_HOST": config.host,
+        "PENPOT_PORT": str(config.port),
+        "PENPOT_VERSION": config.version,
+        "PENPOT_URI": config.url,
+        "PENPOT_SECRET_KEY": secrets.token_urlsafe(48),
+    }
+
+
+def compose(*args: str) -> None:
+    env = {**environment(settings()), **os.environ}
+    command = ["docker", "compose", "-f", str(directory() / "compose.yaml"), *args]
+    subprocess.run(command, check=True, env=env)  # noqa: S603, S607
+
+
+def publish(key: str) -> None:
+    location = (
+        "location = /mcp/claude {\n"
+        f"    rewrite ^ /mcp?userToken={key} break;\n"
+        "    proxy_pass http://penpot-mcp:4401;\n"
+        "    proxy_http_version 1.1;\n"
+        "    proxy_buffering off;\n"
+        "}\n"
+    )
+    script = 'printf "%s" "$1" > /etc/nginx/overrides/server.d/claude-mcp.conf && nginx -s reload'
+    compose("exec", "-T", "penpot-frontend", "sh", "-c", script, "sh", location)

penpot_stack/config/autologin.conf

@@ -0,0 +1,5 @@
+location = /autologin {
+    absolute_redirect off;
+    add_header Set-Cookie "auth-token=$arg_token; Path=/; HttpOnly; SameSite=Lax";
+    return 302 /;
+}

penpot_stack/config/compose.yaml

@@ -0,0 +1,86 @@
+name: ${PENPOT_PROJECT:-penpot-local}
+
+x-flags: &flags
+  PENPOT_FLAGS: >-
+    disable-email-verification disable-secure-session-cookies disable-onboarding
+    enable-access-tokens enable-mcp
+x-uri: &uri
+  PENPOT_PUBLIC_URI: ${PENPOT_URI:-http://localhost:9001}
+x-secret-key: &secret-key
+  PENPOT_SECRET_KEY: ${PENPOT_SECRET_KEY}
+
+volumes:
+  assets:
+
+services:
+  penpot-frontend:
+    image: penpotapp/frontend:${PENPOT_VERSION:-2.17.2}
+    ports:
+      - "${PENPOT_HOST:-127.0.0.1}:${PENPOT_PORT:-9001}:8080"
+    volumes:
+      - assets:/opt/data/assets
+      - ./autologin.conf:/etc/nginx/overrides/server.d/autologin.conf:ro
+    depends_on:
+      - penpot-backend
+      - penpot-exporter
+      - penpot-mcp
+    environment:
+      <<: [*flags, *uri]
+
+  penpot-backend:
+    image: penpotapp/backend:${PENPOT_VERSION:-2.17.2}
+    volumes:
+      - assets:/opt/data/assets
+    depends_on:
+      penpot-postgres:
+        condition: service_healthy
+      penpot-valkey:
+        condition: service_healthy
+    environment:
+      <<: [*flags, *uri, *secret-key]
+      PENPOT_DATABASE_URI: postgresql://penpot-postgres/penpot
+      PENPOT_DATABASE_USERNAME: penpot
+      PENPOT_DATABASE_PASSWORD: penpot
+      PENPOT_REDIS_URI: redis://penpot-valkey/0
+      PENPOT_OBJECTS_STORAGE_BACKEND: fs
+      PENPOT_OBJECTS_STORAGE_FS_DIRECTORY: /opt/data/assets
+      PENPOT_TELEMETRY_ENABLED: "false"
+
+  penpot-mcp:
+    image: penpotapp/mcp:${PENPOT_VERSION:-2.17.2}
+
+  penpot-exporter:
+    image: penpotapp/exporter:${PENPOT_VERSION:-2.17.2}
+    depends_on:
+      penpot-valkey:
+        condition: service_healthy
+    environment:
+      <<: [*uri, *secret-key]
+      PENPOT_INTERNAL_URI: http://penpot-frontend:8080
+      PENPOT_REDIS_URI: redis://penpot-valkey/0
+
+  penpot-postgres:
+    image: postgres:15
+    stop_signal: SIGINT
+    tmpfs:
+      - /var/lib/postgresql/data
+    healthcheck:
+      test: [CMD-SHELL, pg_isready -U penpot]
+      interval: 2s
+      timeout: 10s
+      retries: 5
+      start_period: 2s
+    environment:
+      POSTGRES_DB: penpot
+      POSTGRES_USER: penpot
+      POSTGRES_PASSWORD: penpot
+
+  penpot-valkey:
+    image: valkey/valkey:8.1
+    command: [valkey-server, --save, "", --appendonly, "no"]
+    healthcheck:
+      test: [CMD-SHELL, valkey-cli ping | grep PONG]
+      interval: 1s
+      timeout: 3s
+      retries: 5
+      start_period: 3s

penpot_stack/penpot.py

@@ -0,0 +1,83 @@
+"""The Penpot RPC API: the throwaway profile, the session and the calls the commands need."""
+
+import sys
+import time
+from typing import Any
+
+import httpx
+
+from .settings import settings
+
+
+def profile() -> dict[str, str]:
+    config = settings()
+    return {"email": config.email, "password": config.password}
+
+
+def rpc(client: httpx.Client, command: str, **params: Any) -> Any:
+    response = client.post(f"/api/rpc/command/{command}", json=params)
+    if response.is_error:
+        sys.exit(f"{command}: {response.status_code} {response.text}")
+    return response.json() if response.content else None
+
+
+def stream(client: httpx.Client, command: str, **kwargs: Any) -> str:
+    event = ""
+    with client.stream("POST", f"/api/rpc/command/{command}", **kwargs) as response:
+        if response.is_error:
+            sys.exit(f"{command}: {response.status_code} {response.read().decode()}")
+        for line in response.iter_lines():
+            if line.startswith("event:"):
+                event = line.removeprefix("event:").strip()
+            elif line.startswith("data:") and event in ("end", "error"):
+                if event == "error":
+                    sys.exit(f"{command}: {line}")
+                return line.removeprefix("data:")
+    sys.exit(f"{command}: stream closed without a result")
+
+
+def connect(wait: float) -> httpx.Client | None:
+    client = httpx.Client(
+        base_url=settings().url,
+        headers={"Accept": "application/json"},
+        timeout=60,
+        follow_redirects=True,
+    )
+    deadline = time.monotonic() + wait
+    while True:
+        try:
+            if client.post("/api/rpc/command/get-profile", json={}).is_success:
+                return client
+        except httpx.TransportError:
+            pass
+        if time.monotonic() > deadline:
+            return None
+        time.sleep(2)
+
+
+def session() -> httpx.Client:
+    client = connect(wait=0)
+    if client is None:
+        sys.exit(f"penpot is not answering on {settings().url}, run `up` first")
+    rpc(client, "login-with-password", **profile())
+    return client
+
+
+def register(client: httpx.Client) -> str:
+    token = rpc(client, "prepare-register-profile", fullname="Designer", **profile())["token"]
+    rpc(client, "register-profile", token=token)
+    rpc(client, "update-profile-props", props={"mcpEnabled": True})
+    return str(rpc(client, "create-access-token", name="mcp", type="mcp")["token"])
+
+
+def drafts(client: httpx.Client) -> str:
+    projects = rpc(client, "get-all-projects")
+    return str(next(p["id"] for p in projects if p["isDefault"] and p["isDefaultTeam"]))
+
+
+def files(client: httpx.Client) -> list[tuple[str, str]]:
+    return [
+        (f"{project['name']} / {file['name']}", file["id"])
+        for project in rpc(client, "get-all-projects")
+        for file in rpc(client, "get-project-files", projectId=project["id"])
+    ]

penpot_stack/prompts.py

@@ -0,0 +1,34 @@
+"""Every question the commands ask, so cancelling one always means the same no."""
+
+import re
+from collections.abc import Sequence
+from typing import Any
+
+import questionary
+
+EMPTY = "(empty)"
+NEW = "(new template)"
+SKIP = "(skip export)"
+
+
+def valid(name: str) -> bool:
+    return bool(re.fullmatch(r"[a-z0-9][a-z0-9-]*", name))
+
+
+def select(question: str, choices: Sequence[Any]) -> Any | None:
+    return questionary.select(question, choices=list(choices)).ask()
+
+
+def confirm(question: str) -> bool:
+    return bool(questionary.confirm(question, default=False).ask())
+
+
+def source(existing: Sequence[str], extra: Sequence[str] = ()) -> str | None:
+    return select("Template", [*extra, *existing])
+
+
+def target(existing: Sequence[str]) -> str | None:
+    choice = select("Template", [NEW, *existing])
+    if choice is None or choice != NEW:
+        return choice
+    return questionary.text("Template name", validate=valid).ask()

penpot_stack/settings.py

@@ -0,0 +1,46 @@
+"""Settings: defaults, .penpot.yaml in the working directory, then PENPOT_* variables."""
+
+from pathlib import Path
+
+from pydantic_settings import (
+    BaseSettings,
+    PydanticBaseSettingsSource,
+    SettingsConfigDict,
+    YamlConfigSettingsSource,
+)
+
+FILE = ".penpot.yaml"
+WILDCARD = ("0.0.0.0", "::")  # noqa: S104
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="PENPOT_", yaml_file=FILE, extra="forbid")
+
+    templates: Path = Path("templates")
+    host: str = "127.0.0.1"
+    port: int = 9001
+    project: str = "penpot-local"
+    version: str = "2.17.2"
+    email: str = "designer@example.com"
+    password: str = "penpot-local"  # noqa: S105
+
+    @property
+    def url(self) -> str:
+        # A wildcard bind is still reached as localhost by the browser opened on this machine.
+        host = "localhost" if self.host in (*WILDCARD, "127.0.0.1") else self.host
+        return f"http://{host}:{self.port}"
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        return (init_settings, env_settings, YamlConfigSettingsSource(settings_cls))
+
+
+def settings() -> Settings:
+    return Settings()

penpot_stack/templates.py

@@ -0,0 +1,90 @@
+"""Templates on disk: unpacked Penpot exports the stack imports from and exports back to."""
+
+import io
+import json
+import re
+import shutil
+import sys
+import zipfile
+from pathlib import Path
+
+import httpx
+
+from .penpot import rpc, stream
+from .settings import settings
+
+
+def root() -> Path:
+    return settings().templates.resolve()
+
+
+def names() -> list[str]:
+    return sorted(p.parent.name for p in root().glob("*/manifest.json"))
+
+
+def archives() -> list[Path]:
+    return sorted(Path.cwd().glob("*.penpot"))
+
+
+def pack(source: Path) -> bytes:
+    buffer = io.BytesIO()
+    with zipfile.ZipFile(buffer, "w", zipfile.ZIP_DEFLATED) as archive:
+        for path in sorted(p for p in source.rglob("*") if p.is_file()):
+            archive.write(path, path.relative_to(source).as_posix())
+    return buffer.getvalue()
+
+
+def load(client: httpx.Client, project: str, source: Path) -> None:
+    file_id = json.loads((source / "manifest.json").read_text())["files"][0]["id"]
+    rpc(client, "create-file", id=file_id, name=source.name, projectId=project)
+    stream(
+        client,
+        "import-binfile",
+        data={"name": source.name, "project-id": project, "file-id": file_id},
+        files={"file": (f"{source.name}.penpot", pack(source), "application/zip")},
+    )
+
+
+def download(client: httpx.Client, file_id: str) -> zipfile.ZipFile:
+    result = stream(
+        client,
+        "export-binfile",
+        json={"fileId": file_id, "includeLibraries": False, "embedAssets": True},
+    )
+    # Transit encodes the link either as a tagged string or as a tagged map, depending on Penpot.
+    url = re.search(r'"~r([^"]+)"|"~#uri"\s*:\s*"([^"]+)"', result)
+    if url is None:
+        sys.exit(f"export-binfile: no download link in {result}")
+    response = client.get(url.group(1) or url.group(2))
+    response.raise_for_status()
+    return zipfile.ZipFile(io.BytesIO(response.content))
+
+
+def entries(archive: zipfile.ZipFile) -> list[str]:
+    # Frame thumbnails are raster renders Penpot regenerates, so they never reach the template.
+    thumbnails = [n for n in archive.namelist() if "/thumbnails/" in n]
+    objects = {f"objects/{json.loads(archive.read(n))['mediaId']}." for n in thumbnails}
+    return [
+        n
+        for n in archive.namelist()
+        if n not in thumbnails and not n.startswith(tuple(objects)) and not n.endswith("/")
+    ]
+
+
+def unpack(archive: zipfile.ZipFile, target: Path) -> None:
+    kept = entries(archive)
+    raster = [n for n in kept if not n.endswith((".json", ".svg"))]
+    if raster:
+        sys.exit("only SVG images are allowed, replace these:\n  " + "\n  ".join(raster))
+    shutil.rmtree(target, ignore_errors=True)
+    for name in kept:
+        path = target / name
+        path.parent.mkdir(parents=True, exist_ok=True)
+        content = archive.read(name)
+        if name.endswith(".json"):
+            content = (json.dumps(json.loads(content), indent=2) + "\n").encode()
+        path.write_bytes(content)
+
+
+def save(client: httpx.Client, file_id: str, target: Path) -> None:
+    unpack(download(client, file_id), target)