approvalui 0.1.1__tar.gz

approvalui-0.1.1/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,42 @@
+---
+name: Bug report
+about: Report a problem with ApprovalUI
+title: "[BUG] "
+labels: bug
+assignees: ''
+---
+
+## Describe the bug
+
+A clear and concise description of what the bug is.
+
+## To reproduce
+
+Steps to reproduce the behavior:
+
+1. Run `approvalui ...`
+2. Open `approval.html`
+3. See error
+
+## Expected behavior
+
+What you expected to happen.
+
+## Input JSON
+
+```json
+{
+  "title": "...",
+  "items": []
+}
+```
+
+## Environment
+
+- OS:
+- Python version:
+- ApprovalUI version:
+
+## Additional context
+
+Add any other context, screenshots, or browser console errors here.

approvalui-0.1.1/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,23 @@
+---
+name: Feature request
+about: Suggest an idea for ApprovalUI
+title: "[FEATURE] "
+labels: enhancement
+assignees: ''
+---
+
+## Is your feature request related to a problem?
+
+A clear and concise description of what the problem is.
+
+## Describe the solution you'd like
+
+What should ApprovalUI do?
+
+## Describe alternatives you've considered
+
+Any alternative solutions or features you've considered.
+
+## Additional context
+
+Add any other context or screenshots here.

approvalui-0.1.1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,19 @@
+## What changed
+
+Briefly describe the change.
+
+## Why
+
+What problem does this solve?
+
+## How to test
+
+- `pytest`
+- `ruff check src tests`
+- `mypy src`
+
+## Checklist
+
+- [ ] Tests pass
+- [ ] Lint passes
+- [ ] README or docs updated if needed

approvalui-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dev dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: ruff check src tests
+
+      - name: Check formatting with ruff
+        run: ruff format --check src tests
+
+      - name: Type check with mypy
+        run: mypy src
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package and dev dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest

approvalui-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,48 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/approvalui
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Check for PyPI token
+        id: pypi
+        env:
+          PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
+        run: |
+          if [ -n "$PYPI_TOKEN" ]; then
+            echo "has_token=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "has_token=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Publish to PyPI
+        if: steps.pypi.outputs.has_token == 'true'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_TOKEN }}

approvalui-0.1.1/.gitignore

@@ -0,0 +1,47 @@
+# macOS
+.DS_Store
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# pytest
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Generated example output (kept in repo for demos)
+# example/approval.html

approvalui-0.1.1/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.1] - 2026-06-17
+
+### Added
+
+- GitHub Pages docs site with demo GIF and agent examples.
+- PyPI publishing via GitHub Actions.
+
+## [0.1.0] - 2026-06-15
+
+### Added
+
+- Initial release: `agent-ui-approval` CLI that renders a self-contained HTML approval page from a JSON spec.
+- Approve/reject per item with optional comments.
+- Generate and copy structured review text.
+- Example spec and generated page in `example/`.
+- Floom `SKILL.md` for agent integration.
+
+[Unreleased]: https://github.com/floomhq/approvalui/compare/v0.1.1...HEAD
+[0.1.1]: https://github.com/floomhq/approvalui/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/floomhq/approvalui/releases/tag/v0.1.0

approvalui-0.1.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,25 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Being respectful of differing viewpoints and experiences.
+- Giving and gracefully accepting constructive feedback.
+- Focusing on what is best for the community and users.
+
+Examples of unacceptable behavior:
+
+- Trolling, insulting or derogatory comments, and personal or political attacks.
+- Public or private harassment.
+- Publishing others' private information without permission.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the maintainers at **security@floom.dev**. All complaints will be reviewed and investigated promptly.
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

approvalui-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,41 @@
+# Contributing
+
+Thanks for helping make Agent UI Approval better.
+
+## Quick start
+
+1. Fork the repo and clone your fork.
+2. Create a virtual environment:
+   ```bash
+   python3 -m venv .venv
+   source .venv/bin/activate
+   ```
+3. Install in editable mode with dev dependencies:
+   ```bash
+   pip install -e ".[dev]"
+   ```
+4. Run the tests:
+   ```bash
+   pytest
+   ```
+
+## What to contribute
+
+- Bug fixes for JSON parsing or HTML generation.
+- Tests for edge cases in the spec format.
+- Documentation improvements.
+- UI/UX improvements to the generated approval page.
+
+## Guidelines
+
+- Keep the tool small and focused.
+- Add tests for any new behavior.
+- Update the README if you change the JSON spec or CLI.
+- One logical change per pull request.
+
+## Reporting issues
+
+Open an issue with:
+- The command you ran.
+- The input JSON (or a minimal version of it).
+- What you expected vs. what happened.

approvalui-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agent UI Approval contributors
+
+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.

approvalui-0.1.1/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: approvalui
+Version: 0.1.1
+Summary: Generate a clickable HTML approval page for reviewing UI fixes inside terminal-based AI agents.
+Project-URL: Homepage, https://github.com/floomhq/approvalui
+Project-URL: Repository, https://github.com/floomhq/approvalui
+Project-URL: Issues, https://github.com/floomhq/approvalui/issues
+Project-URL: Changelog, https://github.com/floomhq/approvalui/blob/main/CHANGELOG.md
+Author: Federico de Ponte
+License: MIT License
+        
+        Copyright (c) 2026 Agent UI Approval contributors
+        
+        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.
+License-File: LICENSE
+Keywords: agent,ai,approval,claude,codex,terminal,ui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ApprovalUI
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](pyproject.toml)
+[![Tests](https://github.com/floomhq/approvalui/actions/workflows/ci.yml/badge.svg)](https://github.com/floomhq/approvalui/actions)
+[![PyPI](https://img.shields.io/pypi/v/approvalui.svg)](https://pypi.org/project/approvalui/)
+
+A tiny open-source loop for reviewing UI fixes inside terminal-based AI agents.
+
+Terminal agents are great for code. They are bad at UI feedback, because UI feedback needs eyes, not paragraphs.
+
+ApprovalUI renders a clickable HTML approval page from a simple JSON spec. You open it in a browser, tick approve or reject per item, generate a review, and paste it back into the agent.
+
+Binary signal. Screenshot attached. No drift.
+
+![ApprovalUI demo](docs/assets/approvalui-demo.gif)
+
+---
+
+## Why
+
+When you iterate on frontend with a terminal agent, the feedback loop is verbal:
+
+> “The divider looks weird — can you make it full height?”
+
+The agent reads text, not pixels. You end up describing the same fix five times.
+
+ApprovalUI short-circuits that loop. The agent writes a structured spec of the fixes, you review them visually, and the page gives you a structured text block to paste back.
+
+Works with Claude Code, Codex, Kimi, or any terminal agent that can write JSON and open a browser.
+
+---
+
+## How it works
+
+1. The agent writes a JSON spec describing each UI fix: title, issue number, screenshot, root cause.
+2. `approvalui` turns the spec into a self-contained HTML page.
+3. You open the page, review each item, tick **Approve** or **Reject**, add comments.
+4. Click **Generate review** to get a structured text block you paste back into the agent.
+
+---
+
+## Install
+
+```bash
+pip install approvalui
+```
+
+Or clone and install in editable mode:
+
+```bash
+git clone https://github.com/floomhq/approvalui.git
+cd approvalui
+pip install -e ".[dev]"
+```
+
+---
+
+## Quick start
+
+```bash
+approvalui example/fixes.json example/approval.html
+open example/approval.html
+```
+
+Tick approve or reject, add a comment, and click **Generate review**.
+
+---
+
+## JSON spec format
+
+```json
+{
+  "title": "Workeros — Fix Approval",
+  "instructions": "Tick the ones you approve, click Generate review, paste it back to me.",
+  "items": [
+    {
+      "id": 1218,
+      "title": "Brain split-view divider now runs FULL HEIGHT to the bottom",
+      "status": "pending",
+      "root_cause": "wrapper used min-h-full so Collection height:100% could not resolve",
+      "screenshot": "screenshot.svg"
+    }
+  ]
+}
+```
+
+Only `id` and `title` are required. `root_cause`, `screenshot`, and `instructions` are optional.
+
+---
+
+## Generated review format
+
+```text
+[APPROVE] #1218 — Brain split-view divider now runs FULL HEIGHT to the bottom
+[REJECT] #1219 — Sidebar scrolls horizontally on mobile — comment: still broken on iPhone SE
+```
+
+---
+
+## Documentation
+
+- [Docs site](https://floomhq.github.io/approvalui/)
+- [Architecture](docs/architecture.md)
+- [Advanced usage](docs/advanced.md)
+- [Troubleshooting](docs/troubleshooting.md)
+- [Claude Code example](docs/examples/claude.md)
+- [Codex example](docs/examples/codex.md)
+- [Kimi example](docs/examples/kimi.md)
+
+---
+
+## Files
+
+- `src/approvalui/` — the Python package.
+- `example/` — sample spec, screenshot placeholder, and generated page.
+- `SKILL.md` — Floom skill instructions for agent integration.
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+---
+
+## License
+
+MIT. See [LICENSE](LICENSE).

approvalui-0.1.1/README.md

@@ -0,0 +1,129 @@
+# ApprovalUI
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](pyproject.toml)
+[![Tests](https://github.com/floomhq/approvalui/actions/workflows/ci.yml/badge.svg)](https://github.com/floomhq/approvalui/actions)
+[![PyPI](https://img.shields.io/pypi/v/approvalui.svg)](https://pypi.org/project/approvalui/)
+
+A tiny open-source loop for reviewing UI fixes inside terminal-based AI agents.
+
+Terminal agents are great for code. They are bad at UI feedback, because UI feedback needs eyes, not paragraphs.
+
+ApprovalUI renders a clickable HTML approval page from a simple JSON spec. You open it in a browser, tick approve or reject per item, generate a review, and paste it back into the agent.
+
+Binary signal. Screenshot attached. No drift.
+
+![ApprovalUI demo](docs/assets/approvalui-demo.gif)
+
+---
+
+## Why
+
+When you iterate on frontend with a terminal agent, the feedback loop is verbal:
+
+> “The divider looks weird — can you make it full height?”
+
+The agent reads text, not pixels. You end up describing the same fix five times.
+
+ApprovalUI short-circuits that loop. The agent writes a structured spec of the fixes, you review them visually, and the page gives you a structured text block to paste back.
+
+Works with Claude Code, Codex, Kimi, or any terminal agent that can write JSON and open a browser.
+
+---
+
+## How it works
+
+1. The agent writes a JSON spec describing each UI fix: title, issue number, screenshot, root cause.
+2. `approvalui` turns the spec into a self-contained HTML page.
+3. You open the page, review each item, tick **Approve** or **Reject**, add comments.
+4. Click **Generate review** to get a structured text block you paste back into the agent.
+
+---
+
+## Install
+
+```bash
+pip install approvalui
+```
+
+Or clone and install in editable mode:
+
+```bash
+git clone https://github.com/floomhq/approvalui.git
+cd approvalui
+pip install -e ".[dev]"
+```
+
+---
+
+## Quick start
+
+```bash
+approvalui example/fixes.json example/approval.html
+open example/approval.html
+```
+
+Tick approve or reject, add a comment, and click **Generate review**.
+
+---
+
+## JSON spec format
+
+```json
+{
+  "title": "Workeros — Fix Approval",
+  "instructions": "Tick the ones you approve, click Generate review, paste it back to me.",
+  "items": [
+    {
+      "id": 1218,
+      "title": "Brain split-view divider now runs FULL HEIGHT to the bottom",
+      "status": "pending",
+      "root_cause": "wrapper used min-h-full so Collection height:100% could not resolve",
+      "screenshot": "screenshot.svg"
+    }
+  ]
+}
+```
+
+Only `id` and `title` are required. `root_cause`, `screenshot`, and `instructions` are optional.
+
+---
+
+## Generated review format
+
+```text
+[APPROVE] #1218 — Brain split-view divider now runs FULL HEIGHT to the bottom
+[REJECT] #1219 — Sidebar scrolls horizontally on mobile — comment: still broken on iPhone SE
+```
+
+---
+
+## Documentation
+
+- [Docs site](https://floomhq.github.io/approvalui/)
+- [Architecture](docs/architecture.md)
+- [Advanced usage](docs/advanced.md)
+- [Troubleshooting](docs/troubleshooting.md)
+- [Claude Code example](docs/examples/claude.md)
+- [Codex example](docs/examples/codex.md)
+- [Kimi example](docs/examples/kimi.md)
+
+---
+
+## Files
+
+- `src/approvalui/` — the Python package.
+- `example/` — sample spec, screenshot placeholder, and generated page.
+- `SKILL.md` — Floom skill instructions for agent integration.
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+---
+
+## License
+
+MIT. See [LICENSE](LICENSE).

approvalui-0.1.1/SECURITY.md

@@ -0,0 +1,19 @@
+# Security Policy
+
+## Supported versions
+
+Only the latest release on the `main` branch is actively supported with security updates.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 0.1.x   | :white_check_mark: |
+
+## Reporting a vulnerability
+
+If you discover a security issue, please email **security@floom.dev** with:
+
+- A description of the vulnerability.
+- Steps to reproduce it.
+- The affected version or commit.
+
+We will respond within 5 business days and coordinate a fix and disclosure.