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).
