@nearform/fling 0.6.0 → 0.8.0

package/README.md

@@ -12,7 +12,8 @@ link.
 
 > **Upgrading from 0.2?** The CLI no longer has a built-in server. If you were logged in with 0.2
 > it carries on with the server you logged in to. Otherwise (or on a new machine) run
-> `fling login <url>` once with your Fling's address. See [CHANGELOG.md](CHANGELOG.md).
+> `fling login <url>` once with your Fling's address. See the
+> [changelog](https://github.com/nearform/fling/blob/main/CHANGELOG.md).
 
 ## Install
 
@@ -33,7 +34,8 @@ fling setup https://fling.example.com   # your Fling's address; later runs can l
 This does everything a new machine needs:
 
 1. **Signs you in.** The CLI reads the server's `/.well-known/fling` (its name, where its sites
-   live, how people sign in) and remembers it. Your browser opens for sign-in and an API key is
+   live, how people sign in) and remembers it. Your browser opens for sign-in (on a Fling with two
+   sign-in providers, its login page, to choose one) and an API key is
    stored in `~/.fling/config.json` (mode 0600). This is skipped if you're already signed in.
    The server becomes your current one; logins to other Flings are kept.
 2. **Adds Fling to Claude Code.** If `claude` is on your PATH, setup installs the Fling plugin
@@ -73,7 +75,9 @@ npm run build
 fling deploy ./dist                        # name generated from the project, e.g. rocketpod-docs; you confirm it
 fling deploy ./dist --name my-app          # → https://my-app.<your sites domain>
 fling deploy ./dist --name my-app --spa    # client-side routing: unknown paths serve index.html
-fling deploy ./dist --public               # no sign-in needed to view
+fling deploy ./dist --access members       # a new site everyone signed in can open
+fling deploy ./dist --access people --add bob@example.com   # only you and Bob
+fling deploy ./dist --access public        # no sign-in needed to view
 fling deploy ./dist --yes                  # never prompt (CI): use the generated name as is
 fling deploy                               # deploys the current folder
 fling deploy "Pitch Deck.html"             # a single page, served as index.html → pitch-deck
@@ -101,6 +105,23 @@ does; see below).
 
 - Re-fling to update. Identical content is a no-op, and content you deployed before is restored
   instantly without uploading.
+- **Publish one folder of a site** with `--path` (and `--name`): `fling deploy ./report --name
+  changelog --path 30-10-26` serves the report at `https://changelog.<sites domain>/30-10-26/` and
+  keeps every other file of the site. Only the folder's files are uploaded; the server copies the
+  rest into the new version (at most 1,000 files, else `too_large`: deploy the whole site). If
+  someone else publishes the site in between, the deploy runs once more on top of theirs. `fling
+  versions` shows where each one went (PATH), and rolling back removes it. On a Fling without path
+  publishing (`pathPublish`) the CLI refuses rather than replace the whole site.
+- **Change a site you can open** with `fling pull <name> [dir]`: it downloads the current version
+  into `dir` (default `./<name>`) with a site link, `.fling-site.json`, naming the server, the site
+  and the version pulled. `fling deploy <dir>` then publishes to that site on that version and
+  uploads only what changed (`3 changed, 1 removed`). If someone published the site since you
+  pulled, it stops (`base_changed`) rather than overwrite their work: pull again into another
+  folder and redo your change, or `fling deploy <dir> --force` to replace what they published.
+  `--path <folder>` pulls one folder of the site; `--version-id <id>` another version (owners and
+  publishers). Anyone signed in who can open the site may pull it; only its owners and publishers
+  may deploy. A folder that isn't empty needs `--force`. On a Fling without the `pull` capability
+  the CLI says so.
 - **Fling never publishes dotfiles, gitignored files, secret files (keys, certs, credentials) or
   files that contain secrets; it stops and tells you which file and line.** There is no flag to
   override this, and the server enforces it too.
@@ -180,43 +201,92 @@ and a taken name fails (exit 1) with suggestions rather than picking another nam
 |---|---|
 | `fling ls [--archived] [--sort updated\|created\|name]` | your sites, last updated first (`created`: newest first; `name`: A–Z) |
 | `fling ls --shared [--sort …]` | the restricted sites others have shared with you: owner, and how (your address or a group) |
-| `fling info <name>` / `fling versions <name>` | details and version history |
+| `fling info <name>` / `fling versions <name>` | details and version history, with who published each version and, for a path publish, the folder (PATH) |
+| `fling pull <name> [dir] [--path <folder>] [--version-id <id>] [--force]` | download a site's files to change them; `fling deploy <dir>` publishes on the version pulled |
 | `fling files <name> [versionId]` | the files in the live version (or an earlier one) |
 | `fling rollback <name> <versionId>` | serve an earlier version |
 | `fling share <name> [--refresh] [--revoke]` | public share link: print or create it, rotate it, or remove it |
-| `fling visibility <name> private\|public` | require sign-in, or not |
-| `fling access <name> [--add <emails>] [--remove <emails>] [--group <slugs>] [--remove-group <slugs>] [--clear]` | who can open a private site: everyone signed in, or only listed people and groups |
+| `fling visibility <name> private\|public` | require sign-in, or not (private again: the access it had) |
+| `fling access <name> [--only-me \| --members \| --public] [--add <emails>] [--remove <emails>] [--group <slugs>] [--remove-group <slugs>] [--clear]` | who can open a site: only you, listed people and groups, everyone signed in, or anyone |
+| `fling owners <name> [--add <emails>] [--remove <emails>] [--set <emails>] [--group <slugs>] [--remove-group <slugs>]` | who owns a site, or change it |
+| `fling publishers <name> [--add …] [--remove …] [--set …] [--group …] [--remove-group …]` | who publishes a site without owning it, or change it |
 | `fling archive <name>` / `fling unarchive <name>` | take offline and keep the files, or bring back |
 | `fling rm <name> [--yes]` | delete permanently |
 
-### Who can open a private site
+An admin of the instance can read anyone's site with these commands (`fling info`, `fling files`,
+the comments). Changing someone else's site needs the admin's browser session: open it from All
+sites in the web app.
 
-A private site opens to everyone signed in to your Fling. `fling access` limits it to listed people
-(its audience); you, the owner, can always open it:
+### Who can open a site
+
+Each site has an access level: **only you**, **teams** (groups), **specific people**, **everyone
+signed in** to your Fling, or **public**. A new site gets the one you give with `deploy --access
+only_me|members|groups|people|public` (with `--add <emails>` and `--group <slugs>` for people and
+teams); without it, your Fling's default, which is only you unless it is set up otherwise, and the
+deploy says who can open it. A re-deploy never changes it. `fling ls` shows each site's level in
+its ACCESS column and `fling info` on its Access line.
+
+`fling access` shows and changes it. `--only-me`, `--members` and `--public` set the level; the
+audience options limit the site to listed people and groups (its audience); you, the owner, can
+always open it:
 
 ```sh
 fling access my-app                                   # who can open it now
+fling access my-app --only-me                         # nobody else
+fling access my-app --members                         # everyone signed in
 fling access my-app --add bob@example.com,cat@example.com
 fling access my-app --remove bob@example.com
 fling access my-app --group design                    # everyone in the design group too
 fling access my-app --remove-group design
-fling access my-app --clear                           # everyone signed in again
+fling access my-app --clear                           # empty the audience: everyone signed in
+fling access my-app --public                          # anyone, no sign-in
 ```
 
 Addresses are comma-separated or given after `--add` one by one, and each must be one that can sign
-in to the Fling. Someone who hasn't signed in yet is marked `(hasn't signed in yet)`; they can open
-the site once they do. The audience only applies while the site is private: on a public site it is
+in to the Fling. Where the Fling invites people from outside (its `invites` capability), an outside
+address is invited as a **guest**: a reviewer who signs in with a link emailed to them and sees only
+what is shared with them, marked `(guest)`. You can invite a few new outside addresses a day; past
+that, nothing changes and the CLI says so (`too_many_invites`). The same goes for `fling groups
+create` and `fling groups add`. Someone who hasn't signed in yet is marked `(hasn't signed in yet)`;
+they can open the site once they do. The audience only applies while the site is private: on a public site it is
 kept for later and `fling access` says so. A share link still opens a restricted site to anyone who
 has it, and `fling access` warns while one exists. Removing someone shuts them out within 5
-minutes. `--json` prints the site with its `audience` (`{ emails: [{ email, known }], groups:
+minutes. `--json` prints the site with its `audience` (`{ emails: [{ email, known, guest? }], groups:
 [{ slug, name, size }] }`) and `warnings`; `fling info` shows the same line, and `fling ls --json`
-gives each site's `restricted`, `audienceSize` and `audienceGroups` (how many of those are groups).
+gives each site's `access`, `restricted`, `audienceSize` and `audienceGroups` (how many of those
+are groups). A share link opens a site only you can see as well: it is your choice to hand it out.
 
 `fling ls --shared` lists the other side: the restricted sites whose audience names you, or a group
 you are in, with their owner and how they reached you. With `--json`, each is `{ name, url,
 reviewUrl?, owner, via: { direct, groups }, createdAt, updatedAt }`. Your own sites, and private
 sites open to everyone signed in, aren't listed.
 
+### Owners and publishers
+
+A site's **owners** are equal: each can publish it, roll it back, change who can open it and its
+settings, its owners and publishers, archive and delete it. Its **publishers** can publish and roll
+back, and nothing else. Both are people and groups, and only people who can sign in to your Fling
+as members (never guests) can hold either:
+
+```sh
+fling owners my-app                                   # who owns and publishes it, and your role
+fling owners my-app --add cat@example.com             # Cat owns it too
+fling owners my-app --remove you@example.com          # hand it over (someone else must own it)
+fling publishers my-app --add bob@example.com --group design
+fling publishers my-app --remove-group design
+fling publishers my-app --set bob@example.com         # exactly these addresses (groups stay)
+```
+
+A site always keeps at least one person as an owner, so `--remove` of the last one is refused
+(`last_owner`); a group alone never counts. Someone in both lists is an owner. Naming a group
+trusts whoever manages it: anyone they add owns or publishes the site too. People you add are told
+by email where your Fling sends it. `fling ls` shows your ROLE on each site (owner, publisher, or
+admin for an admin's view), and `fling info` its Owners, Publishers and You. As a publisher,
+`fling deploy` publishes new content, but can't change the site's access or settings (`--access`,
+`--public`, `--spa` that differ: `owner_only`) or bring an archived site back. With `--json`, the
+commands print `{ name, role, owners, publishers }`, each list `{ emails: [{ email, known, guest?
+}], groups: [{ slug, name, size }] }`.
+
 ### Groups
 
 A group is a named list of people, such as a team, that anyone signed in can use in a site's
@@ -257,6 +327,55 @@ feedback (`reviewUrl` in `--json`); reviewers sign in to use it.
 | `fling resolve <name> <id> [--reopen]` | resolve a thread, or reopen it |
 | `fling uncomment <name> <id> [--yes]` | delete a comment (a thread with its replies): your own, or any on your site |
 
+## Forms
+
+A form collects structured feedback on a site's review page: a label per page, rubric scores, an
+A/B preference, a flagged passage's severity. It is a JSON Schema the review page renders, and
+reviewers' answers (responses) come back as data you can export, instead of codes typed into
+comments. On a Fling with forms (the `forms` capability, on with comments), put a
+`fling.forms.json` at the top of the folder you deploy:
+
+```sh
+fling forms init ./dist --template labels --title Labels   # a starter: labels, rubric, compare, issue or survey
+fling forms check ./dist                                   # as a deploy will: errors, and the pages each form applies to
+fling deploy ./dist                                        # sends it as the site's forms (never served as a file)
+fling responses my-app                                     # who answered which page, and how far each form has got
+fling responses my-app --format csv -o labels.csv          # the export: json, jsonl or csv
+```
+
+- `fling deploy` checks the file against the folder's pages and stops on errors. After the deploy
+  it lists each form and the pages it applies to (`forms` in `--json`). Without the file, it ends
+  with one line on adding a form (`formsHint` in `--json`; `--quiet` leaves it out).
+- Without the file, deploying a whole site removes its forms. A `--path` deploy keeps them, and so
+  does a pulled folder, unless it was pulled with a `fling.forms.json` you have since deleted.
+- `fling pull` writes the site's `fling.forms.json` back into the folder.
+- On a form with `"visibility": "own"`, reviewers see only their own answers; the site's owners see
+  everyone's.
+
+| Command | |
+|---|---|
+| `fling forms <name> [--path <page>]` | the live forms: a line per form, then the config as JSON (`> fling.forms.json` saves it) |
+| `fling forms init [dir] [--template <name>] [--title <title>] [--force]` | write a starter `fling.forms.json` |
+| `fling forms check [path]` | check a folder's `fling.forms.json` (or a file) against the folder's pages |
+| `fling responses <name> [--form <id>] [--path <page>] [--format json\|jsonl\|csv] [-o file]` | the responses as a table with progress, or the export |
+
+## Notifications
+
+A Fling with email tells you when a site is shared with you (directly or through a group), when
+you are added to a group, and when someone comments on your site or replies in your thread. You
+choose what you hear about, per event and channel; the same settings are on the web app's
+**Settings → Notifications** page, and every email has a link to stop that kind of email.
+
+| Command | |
+|---|---|
+| `fling notifications` | a table of events × channels: on or off, `*` where you chose it rather than the default |
+| `fling notifications set <event> <channel> on\|off\|default` | change one event on one channel (`default`: back to the Fling's default), e.g. `fling notifications set comment.created email off` |
+| `fling notifications mute` / `unmute` | stop everything, or start again (your choices are kept) |
+| `fling notifications sent` | what was sent to you in the last 30 days: when, the subject and its events |
+
+On a Fling without notifications they say so. `--json` prints the settings as the API returns them
+(`{ channels, events, muted, cells, overrides }`) or `{ sent: [...] }`.
+
 Global options: `--json` prints machine-readable output, and `--server <url>` points one command at
 another server (a remembered one brings its key; see [Several Flings](#several-flings)). Exit codes are `0` ok, `1` error, `2` not logged in and `3` forbidden.
 
@@ -303,9 +422,16 @@ accepts).
 The MCP tools:
 
 - `fling_deploy`: a folder, `.html`, `.zip` or other file on this computer, by path or just its
-  name (looked up like the CLI does).
+  name (looked up like the CLI does). `sitePath` (with `name`) publishes it into that folder of the
+  site and keeps the rest, like `--path`. A folder pulled with `fling pull` or `fling_pull` deploys
+  on the version pulled, like the CLI; `force: true` publishes over whatever is live.
+- `fling_pull`: downloads a site into a folder on this computer (default
+  `~/Documents/Claude/fling/<name>`) to change it and deploy it again with `fling_deploy`.
+- `fling_read_files`: a site's files inline, a page at a time, for reading without a download.
 - `fling_publish`: files passed inline, for content Claude wrote in the conversation. It has the same
-  definition as the remote connector's tool.
+  definition as the remote connector's tool; `path` publishes them into that folder of the site;
+  `base` (a version from `fling_read_files`) sends only the files that changed, and `remove` names
+  files to delete.
 - `fling_find_files`: recent `.html`/`.zip` files and folders with an `index.html` in those folders,
   newest first (last 14 days by default).
 - `fling_login`: opens the browser sign-in. If you haven't finished after about 30 seconds it returns
@@ -315,11 +441,16 @@ The MCP tools:
   current), read when called. `{use: <server>}` makes one current, the same as `fling use`.
 - `fling_check_name`, `fling_list`, `fling_info`, `fling_files`, `fling_share`,
   `fling_set_visibility`, `fling_archive`, `fling_rollback`, `fling_delete` (needs
-  `confirm: true`), `fling_whoami`, the comment tools when a Fling has comments, and
+  `confirm: true`), `fling_whoami`, the comment tools when a Fling has comments, the forms tools when it has forms
+  (`fling_forms`, `fling_forms_template`, `fling_forms_check`, `fling_responses_list`, and
+  `fling_response_submit`, which answers a form as you, only when you ask), and
   `fling_set_audience` (`add`, `remove`, `set` or `clear` the people who can open a private site,
   and `addGroups`, `removeGroups`, `setGroups` for groups) when it can limit sites to listed
-  people, and the group tools (`fling_groups`, `fling_group_show`, `fling_group_create`,
-  `fling_group_members`, `fling_group_rename`, `fling_group_delete`) when it has groups.
+  people, `fling_set_owners` and `fling_set_publishers` (the same changes, to a site's owners or
+  publishers) where it has site roles, and the group tools (`fling_groups`, `fling_group_show`, `fling_group_create`,
+  `fling_group_members`, `fling_group_rename`, `fling_group_delete`) when it has groups, and
+  `fling_notifications` and `fling_notifications_set` (`muted`, and `cells` of
+  `{ event, channel, value: on|off|default }`) when it has notifications.
 
 Results that give URLs (deploys, publishes, comments) end with the Fling they went to.