floop 1.2.0__tar.gz → 2.0.0__tar.gz

floop-2.0.0/.github/workflows/cicd.yml

@@ -0,0 +1,34 @@
+name: Test & Deploy Docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[test]"
+
+      - name: Run tests
+        run: python -m pytest tests/ -v

floop-2.0.0/LICENSE

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

floop-2.0.0/PKG-INFO

@@ -0,0 +1,275 @@
+Metadata-Version: 2.4
+Name: floop
+Version: 2.0.0
+Summary: Project/version review loop CLI and agent skill for AI artifacts
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-cov>=5.0; extra == "test"
+Dynamic: license-file
+
+# floop-client
+
+**AI artifacts need review. floop-client is the review-loop CLI that connects fppt decks and fdesign prototypes to floop-server for structured feedback — without touching artifact internals.**
+
+[![PyPI version](https://img.shields.io/pypi/v/floop?style=for-the-badge)](https://pypi.org/project/floop/)
+[![Python](https://img.shields.io/pypi/pyversions/floop?style=for-the-badge)](https://pypi.org/project/floop/)
+[![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)
+[![Agents](https://img.shields.io/badge/agents-7%20supported-green?style=for-the-badge)](#supported-agents)
+[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen?style=for-the-badge)](#)
+
+---
+
+## The Problem: The "Screenshot Ping-Pong" Trap
+
+You built a beautiful prototype with fdesign or a polished deck with fppt. Now you need feedback from your team, your client, or your stakeholders. What happens next?
+
+Screenshots in Slack. PDFs over email. "Can you make the button bluer?" scattered across three different threads. Feedback arrives out of context, untethered from the specific page or component it references. You spend more time chasing down what people meant than actually improving the artifact.
+
+**Why does this happen?** AI tools are great at *building* artifacts, but they have no built-in mechanism for *reviewing* them. Every team cobbles together their own ad-hoc feedback loop — and every loop leaks context.
+
+```text
+WITHOUT floop-client
+
+  Build v1  →  Screenshot → Slack  →  "Looks good but..."  →  Where was this?
+  Build v2  →  PDF export → Email  →  "Change the header"  →  Which page?
+  Build v3  →  Loom video → Notion  →  "The spacing is off" →  Which component?
+
+  Result: Feedback is everywhere and nowhere. Context is lost.
+```
+
+```text
+WITH floop-client
+
+  Build v1  →  floop review upload  →  shareUrl  →  Reviewers comment inline
+  Fixes     →  Build v2  →  floop review upload  →  New shareUrl
+  Comments  →  floop comments       →  Route to fppt/fdesign  →  Fix & resolve
+
+  Result: Every comment is anchored to a version, a page, and a DOM element.
+```
+
+---
+
+## What floop-client Does
+
+floop-client is the **review-loop layer** between your AI-built artifacts and your reviewers. It does not build decks or prototypes — it creates version containers, uploads them to floop-server, fetches structured comments, and resolves them after fixes.
+
+It is intentionally artifact-agnostic. fppt owns presentation logic. fdesign owns prototype logic. floop-client owns the review pipeline.
+
+```mermaid
+flowchart LR
+    subgraph "Build"
+        fppt["fppt<br/>Decks"]
+        fdesign["fdesign<br/>Prototypes"]
+    end
+
+    subgraph "Review Loop"
+        floop["floop-client<br/>Projects · Versions · Upload · Comments"]
+    end
+
+    subgraph "Server"
+        server["floop-server<br/>Review UI · Comment Threads"]
+    end
+
+    fppt -->|"copies build into version"| floop
+    fdesign -->|"copies build into version"| floop
+    floop -->|"upload"| server
+    server -->|"comments"| floop
+    floop -->|"route fixes"| fppt
+    floop -->|"route fixes"| fdesign
+
+    style floop fill:#e8f4fd,stroke:#2563EB,stroke-width:2px
+```
+
+---
+
+## Why floop-client
+
+### For Makers & Founders
+> You ship fast. Feedback shouldn't slow you down.
+
+Stop juggling screenshots and Slack threads. Publish a version with one command, share a single link, and get structured, anchored feedback that tells you exactly which page and element each comment refers to.
+
+### For Teams (Designers & Developers)
+> Review cycles need structure, not chaos.
+
+Every comment carries a priority, labels (bug, copy, layout, responsive, accessibility), and a DOM anchor. No more "the button on that one page" — reviewers click, comment, and the context travels with the feedback. After fixes, resolve comments to close the loop.
+
+---
+
+## Use Cases
+
+### Scenario 1: Client Review Round
+**Problem:** You built a prototype with fdesign. The client wants to review it. You export screenshots, paste them into a Google Doc, and wait. Three days later, you get back 47 comments — half of them referencing "the blue section" on "that page."
+
+**floop-client Solution:** Run `floop review upload --project my-app --version v1`. Share the `shareUrl`. The client clicks through the prototype on floop-server, clicks any element, and leaves anchored comments. You run `floop comments` to fetch them all, grouped by page and priority.
+
+### Scenario 2: Deck Stakeholder Approval
+**Problem:** You built a presentation with fppt. Marketing, Legal, and the CEO all need to sign off. Each sends feedback in a different format. You spend hours consolidating.
+
+**floop-client Solution:** One `shareUrl` for all stakeholders. Comments are threaded, labeled, and anchored to specific slides. Legal flags get a `legal` label. Marketing feedback gets `copy`. You address them, publish v2, and resolve each comment — full audit trail.
+
+### Scenario 3: Continuous Iteration
+**Problem:** You're iterating fast with AI. Every build is a new version. You need to track what changed, what was reviewed, and what's still open — across multiple versions.
+
+**floop-client Solution:** Each version is independent with its own comment thread. `floop comments --version-id <id>` fetches feedback for a specific version. Reviewers can compare versions side-by-side on floop-server. Nothing falls through the cracks.
+
+---
+
+## Features
+
+- **Local Version Containers**: Create named projects and versions under `.floop/` — artifact services copy their build output in.
+- **One-Command Upload**: `floop review upload` zips and publishes a version to floop-server, returning a `shareUrl`.
+- **Structured Comments**: Fetch anchored, labeled, prioritized feedback — every comment knows its page, element, and viewport.
+- **Comment Resolution**: `floop resolve` marks feedback as addressed after fixes are published.
+- **Local Preview**: `floop preview` serves version directories locally for quick inspection before upload.
+- **Multi-Agent Support**: Install skills into 7 AI agent platforms with `floop enable`.
+
+### Responsibility Boundary
+
+floop-client is intentionally boring. It should remain artifact-agnostic.
+
+| Owned by floop-client | Owned by fppt / fdesign |
+|---|---|
+| `.floop/` workspace | `.fppt/` deck workspace |
+| Project & version containers | `.fdesign/` prototype workspace |
+| `floop review upload` | Deck YAML validation |
+| `floop comments` | Design token validation |
+| `floop resolve` | Component & sitemap logic |
+| `floop preview` | Theme systems |
+| Server project binding | Artifact build output |
+
+### Supported Agents
+
+| Agent | Command |
+|-------|---------|
+| GitHub Copilot | `floop enable copilot` |
+| Cursor | `floop enable cursor` |
+| Claude Code | `floop enable claude` |
+| Trae IDE | `floop enable trae` |
+| Qwen Code | `floop enable qwen-code` |
+| OpenCode | `floop enable opencode` |
+| OpenClaw | `floop enable openclaw` |
+
+---
+
+## Installation
+
+```bash
+pip install floop
+```
+
+Verify:
+
+```bash
+floop --version
+```
+
+---
+
+## Quick Start
+
+```bash
+# 1. Initialize workspace
+cd your-project
+floop init
+
+# 2. Install skills into your AI agent
+floop enable copilot     # or: cursor, claude, trae, qwen-code, opencode, openclaw
+
+# 3. Create a local project and version
+floop projects create my-review
+floop versions create v1 --project my-review --artifact-type fdesign --entrypoint index.html
+
+# 4. Let fppt/fdesign copy artifact files into the version directory
+#    (your AI agent handles this automatically)
+
+# 5. Configure review server and upload
+floop review set --project my-review
+floop review upload --project my-review --version v1 --json-output
+# → shareUrl: https://floop-server.vercel.app/review/...
+
+# 6. Share the link with reviewers, then fetch comments
+floop comments --project my-review --version-id <server-version-id> --json-output
+
+# 7. After fixes are published, resolve addressed comments
+floop resolve <comment-id> --project my-review --version-id <server-version-id> --status resolved
+```
+
+---
+
+## Workspace
+
+```text
+.floop/
+├─ floop.env              # Server URL + API key (no project key)
+├─ config.json            # Workspace metadata
+└─ projects/
+   └─ <project>/
+      ├─ project.json     # Local metadata + serverProject binding
+      └─ versions/
+         └─ <version>/
+            ├─ version.json
+            └─ ...artifact files copied by fppt/fdesign...
+```
+
+---
+
+## Review Loop
+
+```
+┌── Build ──→ Version Container ──→ Upload ──→ Share ──→ Comments ──→ Fix ──┐
+│                                                                           │
+└───────────────────────────────────────────────────────────────────────────┘
+```
+
+1. Artifact service (fppt/fdesign) builds and checks its output.
+2. Agent creates a local floop project/version container.
+3. Agent verifies the local project has the correct `serverProject` binding.
+4. If missing, agent runs `floop review set --project <project>`.
+5. Artifact service copies its build output into the version directory.
+6. `floop review upload` zips and uploads to floop-server.
+7. Agent shares `shareUrl` with the user.
+8. Agent fetches comments with `floop comments`.
+9. Agent routes fixes to fppt, fdesign, or floop-client.
+10. After a fixed version is uploaded, agent resolves addressed comments.
+
+---
+
+## For Contributors
+
+floop-client is the review-loop layer in the floop ecosystem. We welcome contributors who want to expand agent platform support or harden the upload/comment pipeline.
+
+### Getting Started
+
+```bash
+# 1. Fork and clone the repository
+git clone https://github.com/lijma/floop-client.git
+cd floop-client
+
+# 2. Install inside a virtual environment for development
+pip install -e ".[test]"
+
+# 3. Run the test suite (floop-client maintains 100% coverage)
+pytest --cov=floop --cov-report=term-missing --cov-fail-under=100
+
+# 4. Want to add a new AI Agent to `floop enable`?
+# Add yours directly in: src/floop/adapters.py
+```
+
+---
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=lijma/floop-client&type=Date)](https://star-history.com/#lijma/floop-client&Date)
+
+---
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

floop-2.0.0/README.md

@@ -0,0 +1,260 @@
+# floop-client
+
+**AI artifacts need review. floop-client is the review-loop CLI that connects fppt decks and fdesign prototypes to floop-server for structured feedback — without touching artifact internals.**
+
+[![PyPI version](https://img.shields.io/pypi/v/floop?style=for-the-badge)](https://pypi.org/project/floop/)
+[![Python](https://img.shields.io/pypi/pyversions/floop?style=for-the-badge)](https://pypi.org/project/floop/)
+[![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)
+[![Agents](https://img.shields.io/badge/agents-7%20supported-green?style=for-the-badge)](#supported-agents)
+[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen?style=for-the-badge)](#)
+
+---
+
+## The Problem: The "Screenshot Ping-Pong" Trap
+
+You built a beautiful prototype with fdesign or a polished deck with fppt. Now you need feedback from your team, your client, or your stakeholders. What happens next?
+
+Screenshots in Slack. PDFs over email. "Can you make the button bluer?" scattered across three different threads. Feedback arrives out of context, untethered from the specific page or component it references. You spend more time chasing down what people meant than actually improving the artifact.
+
+**Why does this happen?** AI tools are great at *building* artifacts, but they have no built-in mechanism for *reviewing* them. Every team cobbles together their own ad-hoc feedback loop — and every loop leaks context.
+
+```text
+WITHOUT floop-client
+
+  Build v1  →  Screenshot → Slack  →  "Looks good but..."  →  Where was this?
+  Build v2  →  PDF export → Email  →  "Change the header"  →  Which page?
+  Build v3  →  Loom video → Notion  →  "The spacing is off" →  Which component?
+
+  Result: Feedback is everywhere and nowhere. Context is lost.
+```
+
+```text
+WITH floop-client
+
+  Build v1  →  floop review upload  →  shareUrl  →  Reviewers comment inline
+  Fixes     →  Build v2  →  floop review upload  →  New shareUrl
+  Comments  →  floop comments       →  Route to fppt/fdesign  →  Fix & resolve
+
+  Result: Every comment is anchored to a version, a page, and a DOM element.
+```
+
+---
+
+## What floop-client Does
+
+floop-client is the **review-loop layer** between your AI-built artifacts and your reviewers. It does not build decks or prototypes — it creates version containers, uploads them to floop-server, fetches structured comments, and resolves them after fixes.
+
+It is intentionally artifact-agnostic. fppt owns presentation logic. fdesign owns prototype logic. floop-client owns the review pipeline.
+
+```mermaid
+flowchart LR
+    subgraph "Build"
+        fppt["fppt<br/>Decks"]
+        fdesign["fdesign<br/>Prototypes"]
+    end
+
+    subgraph "Review Loop"
+        floop["floop-client<br/>Projects · Versions · Upload · Comments"]
+    end
+
+    subgraph "Server"
+        server["floop-server<br/>Review UI · Comment Threads"]
+    end
+
+    fppt -->|"copies build into version"| floop
+    fdesign -->|"copies build into version"| floop
+    floop -->|"upload"| server
+    server -->|"comments"| floop
+    floop -->|"route fixes"| fppt
+    floop -->|"route fixes"| fdesign
+
+    style floop fill:#e8f4fd,stroke:#2563EB,stroke-width:2px
+```
+
+---
+
+## Why floop-client
+
+### For Makers & Founders
+> You ship fast. Feedback shouldn't slow you down.
+
+Stop juggling screenshots and Slack threads. Publish a version with one command, share a single link, and get structured, anchored feedback that tells you exactly which page and element each comment refers to.
+
+### For Teams (Designers & Developers)
+> Review cycles need structure, not chaos.
+
+Every comment carries a priority, labels (bug, copy, layout, responsive, accessibility), and a DOM anchor. No more "the button on that one page" — reviewers click, comment, and the context travels with the feedback. After fixes, resolve comments to close the loop.
+
+---
+
+## Use Cases
+
+### Scenario 1: Client Review Round
+**Problem:** You built a prototype with fdesign. The client wants to review it. You export screenshots, paste them into a Google Doc, and wait. Three days later, you get back 47 comments — half of them referencing "the blue section" on "that page."
+
+**floop-client Solution:** Run `floop review upload --project my-app --version v1`. Share the `shareUrl`. The client clicks through the prototype on floop-server, clicks any element, and leaves anchored comments. You run `floop comments` to fetch them all, grouped by page and priority.
+
+### Scenario 2: Deck Stakeholder Approval
+**Problem:** You built a presentation with fppt. Marketing, Legal, and the CEO all need to sign off. Each sends feedback in a different format. You spend hours consolidating.
+
+**floop-client Solution:** One `shareUrl` for all stakeholders. Comments are threaded, labeled, and anchored to specific slides. Legal flags get a `legal` label. Marketing feedback gets `copy`. You address them, publish v2, and resolve each comment — full audit trail.
+
+### Scenario 3: Continuous Iteration
+**Problem:** You're iterating fast with AI. Every build is a new version. You need to track what changed, what was reviewed, and what's still open — across multiple versions.
+
+**floop-client Solution:** Each version is independent with its own comment thread. `floop comments --version-id <id>` fetches feedback for a specific version. Reviewers can compare versions side-by-side on floop-server. Nothing falls through the cracks.
+
+---
+
+## Features
+
+- **Local Version Containers**: Create named projects and versions under `.floop/` — artifact services copy their build output in.
+- **One-Command Upload**: `floop review upload` zips and publishes a version to floop-server, returning a `shareUrl`.
+- **Structured Comments**: Fetch anchored, labeled, prioritized feedback — every comment knows its page, element, and viewport.
+- **Comment Resolution**: `floop resolve` marks feedback as addressed after fixes are published.
+- **Local Preview**: `floop preview` serves version directories locally for quick inspection before upload.
+- **Multi-Agent Support**: Install skills into 7 AI agent platforms with `floop enable`.
+
+### Responsibility Boundary
+
+floop-client is intentionally boring. It should remain artifact-agnostic.
+
+| Owned by floop-client | Owned by fppt / fdesign |
+|---|---|
+| `.floop/` workspace | `.fppt/` deck workspace |
+| Project & version containers | `.fdesign/` prototype workspace |
+| `floop review upload` | Deck YAML validation |
+| `floop comments` | Design token validation |
+| `floop resolve` | Component & sitemap logic |
+| `floop preview` | Theme systems |
+| Server project binding | Artifact build output |
+
+### Supported Agents
+
+| Agent | Command |
+|-------|---------|
+| GitHub Copilot | `floop enable copilot` |
+| Cursor | `floop enable cursor` |
+| Claude Code | `floop enable claude` |
+| Trae IDE | `floop enable trae` |
+| Qwen Code | `floop enable qwen-code` |
+| OpenCode | `floop enable opencode` |
+| OpenClaw | `floop enable openclaw` |
+
+---
+
+## Installation
+
+```bash
+pip install floop
+```
+
+Verify:
+
+```bash
+floop --version
+```
+
+---
+
+## Quick Start
+
+```bash
+# 1. Initialize workspace
+cd your-project
+floop init
+
+# 2. Install skills into your AI agent
+floop enable copilot     # or: cursor, claude, trae, qwen-code, opencode, openclaw
+
+# 3. Create a local project and version
+floop projects create my-review
+floop versions create v1 --project my-review --artifact-type fdesign --entrypoint index.html
+
+# 4. Let fppt/fdesign copy artifact files into the version directory
+#    (your AI agent handles this automatically)
+
+# 5. Configure review server and upload
+floop review set --project my-review
+floop review upload --project my-review --version v1 --json-output
+# → shareUrl: https://floop-server.vercel.app/review/...
+
+# 6. Share the link with reviewers, then fetch comments
+floop comments --project my-review --version-id <server-version-id> --json-output
+
+# 7. After fixes are published, resolve addressed comments
+floop resolve <comment-id> --project my-review --version-id <server-version-id> --status resolved
+```
+
+---
+
+## Workspace
+
+```text
+.floop/
+├─ floop.env              # Server URL + API key (no project key)
+├─ config.json            # Workspace metadata
+└─ projects/
+   └─ <project>/
+      ├─ project.json     # Local metadata + serverProject binding
+      └─ versions/
+         └─ <version>/
+            ├─ version.json
+            └─ ...artifact files copied by fppt/fdesign...
+```
+
+---
+
+## Review Loop
+
+```
+┌── Build ──→ Version Container ──→ Upload ──→ Share ──→ Comments ──→ Fix ──┐
+│                                                                           │
+└───────────────────────────────────────────────────────────────────────────┘
+```
+
+1. Artifact service (fppt/fdesign) builds and checks its output.
+2. Agent creates a local floop project/version container.
+3. Agent verifies the local project has the correct `serverProject` binding.
+4. If missing, agent runs `floop review set --project <project>`.
+5. Artifact service copies its build output into the version directory.
+6. `floop review upload` zips and uploads to floop-server.
+7. Agent shares `shareUrl` with the user.
+8. Agent fetches comments with `floop comments`.
+9. Agent routes fixes to fppt, fdesign, or floop-client.
+10. After a fixed version is uploaded, agent resolves addressed comments.
+
+---
+
+## For Contributors
+
+floop-client is the review-loop layer in the floop ecosystem. We welcome contributors who want to expand agent platform support or harden the upload/comment pipeline.
+
+### Getting Started
+
+```bash
+# 1. Fork and clone the repository
+git clone https://github.com/lijma/floop-client.git
+cd floop-client
+
+# 2. Install inside a virtual environment for development
+pip install -e ".[test]"
+
+# 3. Run the test suite (floop-client maintains 100% coverage)
+pytest --cov=floop --cov-report=term-missing --cov-fail-under=100
+
+# 4. Want to add a new AI Agent to `floop enable`?
+# Add yours directly in: src/floop/adapters.py
+```
+
+---
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=lijma/floop-client&type=Date)](https://star-history.com/#lijma/floop-client&Date)
+
+---
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

{floop-1.2.0 → floop-2.0.0}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "floop"
 dynamic = ["version"]
-description = "AI-native prototype quality toolkit — Agent Skill + review workflow CLI"
+description = "Project/version review loop CLI and agent skill for AI artifacts"
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.10"

{floop-1.2.0 → floop-2.0.0}/src/floop/__init__.py

@@ -1,4 +1,4 @@
-"""floop — AI-native prototype quality toolkit."""
+"""floop-client — project/version review loop for AI artifacts."""
 
 from importlib.metadata import PackageNotFoundError, version
 

{floop-1.2.0 → floop-2.0.0}/src/floop/adapters.py

@@ -42,8 +42,7 @@ class CopilotAdapter:
         instr_path = instr_dir / "floop.instructions.md"
         instr_path.write_text(
             "---\n"
-            "description: 'This project uses floop for prototype development. "
-            "Follow the floop workflow for design tokens, sitemap, components, and page generation.'\n"
+            "description: 'This project uses floop-client for artifact review projects, versions, uploads, and comments.'\n"
             "applyTo: '**'\n"
             "---\n\n"
             + INSTRUCTION,
@@ -91,7 +90,7 @@ class CursorAdapter:
         instr_path = rules_dir / "floop.mdc"
         instr_path.write_text(
             '---\n'
-            'description: "floop prototype workflow — always-on context"\n'
+            'description: "floop-client review workflow — always-on context"\n'
             'globs: \n'
             'alwaysApply: true\n'
             '---\n\n'