Metadata-Version: 2.4
Name: floop
Version: 2.0.1
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

**floop-client is the CLI for project/version uploads and server comments.**

[![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)
[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen?style=for-the-badge)](#)

floop-client is intentionally small. It helps agents and users choose the right
local project/version, upload the right files to floop-server, read server
comments, and resolve comments after a newer version addresses them.

It does not build artifacts, validate design tokens, generate UI, or decide
which files belong to another tool. The tool or user that owns the files places
them in a floop version directory; floop handles the upload and comment loop.

## Core Flow

```text
Create/select project -> Create/select version -> Add files -> Upload -> Read comments -> Resolve comments
```

## Installation

```bash
pip install floop
```

Verify:

```bash
floop --version
```

## Quick Start

```bash
# 1. Initialize workspace
cd your-project
floop init

# 2. Install the floop skill into your AI agent
floop enable copilot     # or: cursor, claude, trae, qwen-code, opencode, openclaw

# 3. Create and select a local project
floop projects create my-review
floop projects use my-review

# 4. Create and select a version
floop versions create v1 --project my-review --artifact-type custom --entrypoint index.html
floop versions use v1 --project my-review

# 5. Put uploadable files in .floop/my-review/v1/

# 6. Configure server access and upload
floop review set --project my-review
floop review upload --project my-review --version v1 --json-output

# 7. Read server comments and cache them locally
floop comments --project my-review --version v1 --version-id <server-version-id> --json-output

# 8. Resolve addressed comments after a newer version has been uploaded
floop resolve <comment-id> --project my-review --version-id <server-version-id> --status resolved
```

## Workspace

```text
.floop/
├─ floop.env              # Server URL + API key only
├─ projects.csv           # Local projects, server bindings, selected project/version
└─ <projectid>/
   └─ <version>/
      ├─ floop.version.json
      ├─ floop.upload.json
      ├─ floop.comments.json
      └─ ...uploadable files...
```

`.floop/floop.env` contains secrets. floop-client warns through docs and command
copy, but it does not create or edit `.floop/.gitignore`; ignore policy belongs
to the host repository.

Legacy workspaces under `.floop/projects/<project>/versions/<version>/` are
readable for compatibility. floop-client does not move or delete legacy files
automatically.

## Commands

### Workspace

```bash
floop init
floop preview
```

### Projects

```bash
floop projects
floop projects create <project>
floop projects use <project>
```

### Versions

```bash
floop versions --project <project>
floop versions create <version> --project <project> --artifact-type <type> --entrypoint index.html
floop versions use <version> --project <project>
```

When a project and version are selected, commands that support defaults can use
the selected values.

### Server

```bash
floop review set --project <project>
floop review upload --project <project> --version <version> --json-output
floop comments --project <project> --version <local-version> --version-id <server-version-id> --json-output
floop resolve <comment-id> --project <project> --version-id <server-version-id> --status resolved
```

## Responsibility Boundary

| floop-client owns | Other tools or users own |
|---|---|
| `.floop/` workspace | Source files |
| `projects.csv` project/version selection | File generation |
| Server project binding | File validation |
| Version upload | Build systems |
| Server comments cache | Artifact internals |
| Comment status updates | Content changes |

## 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` |

## For Contributors

Run the full test gate:

```bash
PYTHONPATH=src python3 -m pytest --cov=floop --cov-report=term-missing --cov-fail-under=100
```
