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

**floop is an agent skill and CLI for uploading local project versions to
floop-server and reading 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 gives agents a small, repeatable workflow:

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

It does not build files, validate artifact internals, generate UI, or decide
which files belong in a version. Other tools or users create the files. floop
stores local project/version state, uploads version directories, caches server
comments, and updates comment status.

## Quick Start for Agents

Use this flow when a user asks to publish with floop:

1. Confirm which floop server to use.
   - SaaS: `https://floop-server.vercel.app`
   - Custom/self-hosted: ask for the full server URL, for example `http://localhost:3000`
2. After the server URL is known, tell the user where to create an API key:
   `<server-url>/dashboard` -> top-right user menu -> `API Keys`.
3. Initialize floop with the server URL and key:

```bash
floop init --server-url <server-url> --api-key <key>
```

4. Create or select a local project:

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

5. Create or select a version:

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

6. Put uploadable files in `.floop/<project>/<version>/`.
7. Upload:

```bash
floop review upload --project <project> --version <version> --json-output
```

8. Give the user `previewUrl`. The CLI upload API does not require or return a
   `shareUrl`; users can open the preview UI and click `Share`.
9. Read comments when requested:

```bash
floop comments --project <project> --version <version> --version-id <server-version-id> --json-output
```

10. Resolve only comments that were addressed by a newer uploaded version:

```bash
floop resolve <comment-id> --project <project> --version-id <server-version-id> --status resolved
```

Agent rules:

- Do not invent API keys or search unrelated files for secrets.
- Do not leave commands waiting for hidden API key input.
- Do not treat missing `shareUrl` as an upload failure.
- Do not modify artifact files unless the user asked for that work.

## Install

```bash
pip install floop
floop --version
```

## Enable the Agent Skill

Install the `floop` skill into the agent platform used by the current project:

```bash
floop enable copilot
floop enable cursor
floop enable claude
floop enable trae
floop enable qwen-code
floop enable opencode
floop enable openclaw
floop enable codex
floop enable pi
floop enable agent
```

The installed skill is named `floop`.

## Quick Start for Humans

```bash
cd your-project

# Initialize workspace and server settings.
floop init --server-url http://localhost:3000 --api-key <key>

# Create/select local state.
floop projects create my-review
floop projects use my-review
floop versions create v1 --project my-review --artifact-type custom --entrypoint index.html
floop versions use v1 --project my-review

# Put uploadable files in .floop/my-review/v1/, then upload.
floop review upload --project my-review --version v1 --json-output

# Read server comments.
floop comments --project my-review --version v1 --version-id <server-version-id> --json-output
```

## Server Setup

`floop init` accepts server settings:

```bash
floop init --server-url <server-url> --api-key <key>
```

If the API key is not available yet:

1. Open `<server-url>/dashboard`.
2. Use the top-right user menu.
3. Choose `API Keys`.
4. Create a key.
5. Rerun `floop init --server-url <server-url> --api-key <key>`.

You can also set `FLOOP_API_KEY` in the environment or in `.floop/floop.env`.

## Upload Contract

The upload API succeeds when it returns `previewUrl`.

```json
{
  "uploaded": true,
  "previewUrl": "https://...",
  "shareUrl": null
}
```

`shareUrl` is not part of the CLI upload contract. Open the preview UI and use
the `Share` button when a share link is needed.

## Workspace Layout

```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 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 does not move or delete legacy files
automatically.

## Commands

### Workspace

```bash
floop init --server-url <server-url> --api-key <key>
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> --server-url <server-url> --api-key <key>
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 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` |
| Codex | `floop enable codex` |
| Pi | `floop enable pi` |
| Agent Skills-compatible agent | `floop enable agent` |

## Development

Run the full test gate:

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