penpot-local-stack 0.1.0__tar.gz

penpot_local_stack-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+# Agents Configs
+.claude/
+.gemini/
+CLAUDE.local.md
+GEMINI.md
+.mcp.json
+
+# IDE
+.venv
+.idea
+
+# Python build and test artifacts
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+.pytest_cache/
+
+# pre-commit cache, kept in-tree by PRE_COMMIT_HOME
+.pre-commit
+
+# Local stack settings, written by install.sh
+.penpot.yaml

penpot_local_stack-0.1.0/.penpot.yaml.example

@@ -0,0 +1,9 @@
+# Penpot local stack. Copy to .penpot.yaml and edit; install.sh does that for
+# you. Remove a key to fall back to its default, or override it in the
+# environment as PENPOT_PORT, PENPOT_TEMPLATES and so on.
+
+templates: templates
+host: 127.0.0.1
+port: 9001
+project: penpot-local
+version: 2.17.2

penpot_local_stack-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,121 @@
+# Contributing
+
+Everything in the checkout runs through `make`, on the system `python3`:
+there is no virtualenv here and nothing installs itself. Python 3.12 or newer
+with the packages from `requirements.txt`, Docker with the Compose plugin, and
+[uv](https://docs.astral.sh/uv/) for `make build`.
+
+- [Layout](#layout)
+- [Make targets](#make-targets)
+- [Working on the stack](#working-on-the-stack)
+- [Tests and linters](#tests-and-linters)
+- [Continuous integration](#continuous-integration)
+- [Releases](#releases)
+
+## Layout
+
+```text
+bin/penpot-stack   launcher, runs the code straight from the checkout
+libs/              the modules: cli, settings, compose, penpot, templates, prompts
+config/            compose.yaml and autologin.conf
+install/           the curl installer and its documentation
+tests/             pytest suite, no network and no Docker
+```
+
+The wheel carries `libs/` and `config/` under one importable name: the build
+maps `libs` to `penpot_stack` and `config` to `penpot_stack/config`, so the
+Compose file ships with the code and `penpot-stack` runs from anywhere. That
+mapping lives in `[tool.hatch.build.targets.wheel]` in `pyproject.toml`.
+
+Modules import each other relatively, which is what lets the same files work
+as `libs` in the checkout and as `penpot_stack` once installed.
+
+`libs/settings.py` is the only place that decides anything configurable: a
+pydantic-settings model filled from defaults, then `.penpot.yaml` in the
+working directory, then `PENPOT_*` variables. `config/compose.yaml` reads the
+same names through `${PENPOT_PORT:-9001}` style defaults, so the file still
+runs under a bare `docker compose`. `.penpot.yaml.example` in the repository
+root is the documented shape of that file and what `install.sh` copies into a
+directory; `.penpot.yaml` itself is gitignored, so the checkout runs on the
+defaults until you copy the example over.
+
+Nothing in the checkout installs that package, so an editable install never
+comes up - which is just as well, because hatchling rejects a dev-mode install
+whose `sources` rewrite replaces a prefix.
+
+## Make targets
+
+| Target         | What it does                                               |
+| -------------- | ---------------------------------------------------------- |
+| `make`         | Open an interactive subshell with `PRE_COMMIT_HOME` set    |
+| `make test`    | Run the pytest suite                                       |
+| `make lint`    | Run the pre-commit hooks over every file                   |
+| `make up`      | Start the stack from the checkout                          |
+| `make down`    | Offer the export, confirm the wipe, stop the stack         |
+| `make import`  | Import a template into the running stack                   |
+| `make export`  | Export a file back into `templates/`                       |
+| `make extract` | Unpack a `.penpot` file into `templates/`, no stack needed |
+| `make convert` | Pack a template into a `.penpot` file, no stack needed     |
+| `make build`   | Build the wheel and the sdist into `dist/`                 |
+| `make clean`   | Remove the build artifacts                                 |
+
+Start by giving your `python3` what `requirements.txt` lists, however this
+machine installs packages, then wire up the hooks once:
+
+```bash
+pre-commit install
+```
+
+## Working on the stack
+
+`make up` and the rest run `python3 bin/penpot-stack`, so they use the working
+tree against `templates/` in the repository root. Point `PENPOT_TEMPLATES` somewhere else to keep the repository clean:
+
+```bash
+PENPOT_TEMPLATES=~/mockups make up
+```
+
+The stack itself is `config/compose.yaml`: Penpot frontend, backend, exporter
+and MCP, with Postgres on tmpfs and Valkey without persistence. Nothing in it
+is meant to survive `down`.
+
+## Tests and linters
+
+```bash
+make test
+make lint
+```
+
+The tests cover the parts that do not need Penpot: template discovery, the
+export filter that drops thumbnails and refuses raster images, the Compose
+command, and every confirm in the command flow. Anything that talks to the
+API is mocked, so the suite needs neither network nor Docker.
+
+`make lint` runs ruff, shellcheck, shfmt, markdownlint and the commit-message
+checks through pre-commit. Both are expected to pass before a commit.
+
+## Continuous integration
+
+`.github/workflows/ci.yml` runs on every pull request and on pushes to `main`:
+one job runs the pre-commit hooks over all files, the other runs the suite on
+Python 3.12, 3.13 and 3.14. Actions are pinned by commit, with the version in
+a trailing comment. Nothing is published from CI.
+
+Dependabot watches three ecosystems weekly: `pip` for `requirements.txt`,
+`pre-commit` for the hook revisions and `github-actions` for those pins.
+
+## Releases
+
+The version lives in `pyproject.toml` and is bumped with commitizen, which
+writes the changelog and the tag:
+
+```bash
+cz bump
+git push --follow-tags
+```
+
+Users upgrade by re-running `install/install.sh`, which unfolds a tag with
+`--ref`, so a release is the tag itself.
+
+`make build` puts the wheel and the sdist in `dist/`. Uploading them is not
+wired into this repository, by hand or from CI.

penpot_local_stack-0.1.0/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_local_stack-0.1.0/Makefile

@@ -0,0 +1,84 @@
+# Developer entry points for penpot-local-stack. Run `make help` for the list.
+
+VENV ?= .venv
+PYTHON := $(VENV)/bin/python
+PIP := $(VENV)/bin/pip
+UV ?= uv
+STACK := $(PYTHON) bin/penpot-stack
+
+VERSION := $(shell sed -n 's/^version = "\(.*\)"/\1/p' pyproject.toml)
+
+# Hook environments live in the repository, not in ~/.cache/pre-commit.
+export PRE_COMMIT_HOME := $(CURDIR)/.pre-commit
+
+.DEFAULT_GOAL := shell
+
+.PHONY: help install lint test shell up down import export extract convert
+.PHONY: build clean require-uv
+
+help:  ## Show the current version and the available targets
+	@echo "penpot-local-stack $(VERSION)"
+	@echo
+	@echo "Targets:"
+	@awk 'BEGIN {FS = ":.*## "} /^[a-z-]+:.*## / {printf "  %-9s %s\n", $$1, $$2}' \
+		$(MAKEFILE_LIST)
+
+
+# development
+install:  ## Create the virtualenv, install everything and wire up the hooks
+	python3 -m venv --prompt penpot-local-stack $(VENV)
+	$(PIP) install --upgrade pip
+	$(PIP) install -r requirements.txt
+	$(VENV)/bin/pre-commit install
+
+lint:  ## Run the pre-commit hooks over every file
+	$(VENV)/bin/pre-commit run --all-files
+
+test:  ## Run the test suite
+	$(VENV)/bin/pytest
+
+
+# stack
+up:  ## Start the stack, import a template and open the browser logged in
+	$(STACK) up
+
+down:  ## Offer to export, then stop the stack and wipe everything it holds
+	$(STACK) down
+
+import:  ## Import a template from templates/ into the running stack
+	$(STACK) import
+
+export:  ## Export a file from the running stack back into templates/
+	$(STACK) export
+
+
+# archives
+extract:  ## Unpack a .penpot file from this directory into templates/
+	$(STACK) extract
+
+convert:  ## Pack a template from templates/ into a .penpot file
+	$(STACK) convert
+
+
+# packaging
+build: require-uv clean  ## Build the wheel and the sdist into dist/
+	$(UV) build
+
+clean:  ## Remove the build artifacts from dist/
+	rm -f dist/*.whl dist/*.tar.gz
+
+require-uv:
+	@command -v $(UV) >/dev/null 2>&1 || { \
+		echo "$(UV) not found, install it first:" >&2; \
+		echo "  https://docs.astral.sh/uv/getting-started/installation/" >&2; \
+		exit 1; \
+	}
+
+
+# defaults
+shell:  ## Open an interactive subshell with the virtualenv activated
+	@rc="$$(mktemp)"; \
+	trap 'rm -f "$$rc"' EXIT; \
+	cat ~/.bashrc 2> /dev/null > "$$rc" || true; \
+	echo 'source $(CURDIR)/$(VENV)/bin/activate' >> "$$rc"; \
+	bash --rcfile "$$rc" -i || true

penpot_local_stack-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,155 @@
+# 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/bin/penpot-stack

@@ -0,0 +1,12 @@
+#!/usr/bin/env python3
+"""Run the stack from a checkout, without installing the package."""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from libs.cli import main  # noqa: E402
+
+if __name__ == "__main__":
+    main()

penpot_local_stack-0.1.0/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 /;
+}