@nearform/fling 0.7.0 → 0.9.0

package/README.md

@@ -38,13 +38,64 @@ This does everything a new machine needs:
    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.
+   When you are already signed in, it reads the server's `/.well-known/fling` again, so the CLI
+   knows the release it runs now.
 2. **Adds Fling to Claude Code.** If `claude` is on your PATH, setup installs the Fling plugin
-   (skill + MCP server) from the `nearform/fling` marketplace, or updates it if it's already
-   installed. `--scope project|local` installs it for this project only (default `user`).
+   (skill + MCP server) from the `nearform/fling` marketplace. `--scope project|local` installs it
+   for this project only (default `user`). When the plugin is already installed, setup refreshes
+   it instead (`claude plugin marketplace update fling`, then `claude plugin update fling@fling`)
+   and says which version it went from and to; restart Claude Code (or run `/reload-plugins`)
+   after an update. A refresh that fails is reported and leaves the installed plugin as it was;
+   it doesn't fail setup.
 3. **Adds Fling to Claude Desktop.** If Claude Desktop is installed (macOS, Windows), setup
-   downloads `fling.mcpb` and opens it, and Claude Desktop asks you to confirm.
+   downloads the `fling.mcpb` of the CLI's own version and opens it, and Claude Desktop asks you
+   to confirm. That is the server's copy when the server runs the same release, otherwise the one
+   attached to the CLI's GitHub Release (the server's copy if that download fails). Running setup
+   again updates an older extension in place.
 
-On a terminal it asks before steps 2 and 3. With `--yes` it does them without asking.
+On a terminal it asks before installing the plugin and before step 3. With `--yes` it does them
+without asking. Refreshing an installed plugin needs no question.
+
+### Staying up to date
+
+Every Fling publishes the release it runs (`release` in `/.well-known/fling`). After a command, when
+the server it used runs a newer release than the CLI, the CLI prints one line on stderr:
+
+```
+▲ Fling 0.9.0 is out (this CLI is 0.8.0). Update: npm i -g @nearform/fling@latest && fling setup
+```
+
+It compares with the metadata the CLI already holds, so it never makes a request of its own. The
+stored release stays current because every server response says which release the server runs (the
+`Fling-Release` header): when it differs from the stored one, the CLI stores the new release. That
+needs both the server and the CLI on a release after 0.8.0; with an older server, the stored release
+changes only at sign-in, when `fling setup` reads the metadata again, and when a command needs a
+feature the stored copy lacks. It says it at most once a day per server, remembering when in
+`update-check.json` in the config directory. It says nothing under `--json`, when stderr isn't a
+terminal, when `CI` is set, or when `FLING_NO_UPDATE_CHECK` is set (to anything). A server older
+than the CLI says nothing either. The MCP server tells Claude instead (see [Claude Code plugin and
+MCP](#claude-code-plugin-and-mcp)).
+
+### When something doesn't work
+
+`fling doctor` checks the setup and prints one line per check, `✔` ok, `▲` warning or `✖` problem,
+each warning and problem with its fix:
+
+- **CLI:** its version, Node.js against the versions it supports, the latest version on npm
+  (skipped when npm can't be reached), and whether `fling` on your PATH is this CLI.
+- **Config:** where it lives (`FLING_CONFIG_DIR`), whether the config file is private (mode 0600:
+  it holds your API keys), and whether `FLING_URL` or `FLING_API_KEY` is in effect (named, never
+  shown).
+- **Each Fling** you signed in to, the current one marked: whether its `/.well-known/fling`
+  answers, the release it runs against the CLI's, whether your API key is still accepted, and the
+  features it reports.
+- **Claude Code:** `claude` on your PATH, the Fling plugin (installed, enabled, its version against
+  the CLI's) and the `fling` marketplace.
+- **Claude Desktop:** whether the extension is installed, enabled, and its version.
+
+It only reads: it changes nothing, and each request has a short timeout. `--json` prints
+`{ ok, checks: [{ area, id, status, message, fix?, server? }] }`. The exit code is 1 when any check
+is a problem.
 
 To sign in only, use `fling login <url>` (the URL is remembered: later `fling login` needs none).
 There is no default server: until you log in, commands say to run `fling login <url>`.
@@ -327,6 +378,38 @@ 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
@@ -350,7 +433,8 @@ another server (a remembered one brings its key; see [Several Flings](#several-f
 Environment: `FLING_API_KEY`, `FLING_URL`, `FLING_CONFIG_DIR`, `FLING_DEBUG`, `FLING_DOWNLOADS_DIR`
 (where the MCP server looks for files given by name first), `FLING_ADD_SERVER` (a Fling the MCP
 server adds to the remembered ones when it starts), `FLING_NO_WAIT=1` (after a deploy or a new share
-link, don't wait the few seconds it takes to reach every edge).
+link, don't wait the few seconds it takes to reach every edge), `FLING_NO_UPDATE_CHECK` (never say
+that a newer Fling release is out; see [Staying up to date](#staying-up-to-date)).
 
 ## Claude Code plugin and MCP
 
@@ -407,9 +491,13 @@ The MCP tools:
   Fling, including a new one, which becomes current only if none is.
 - `fling_servers`: lists the Flings on this computer (address, name, who is signed in, which is
   current), read when called. `{use: <server>}` makes one current, the same as `fling use`.
+- `fling_doctor`: the checks of `fling doctor`, read-only, as lines and data. Claude calls it when
+  something about Fling doesn't work (sign-in, tools missing, versions) and tells you the fixes.
 - `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, `fling_set_owners` and `fling_set_publishers` (the same changes, to a site's owners or
@@ -420,6 +508,11 @@ The MCP tools:
 
 Results that give URLs (deploys, publishes, comments) end with the Fling they went to.
 
+**Updates.** When a Fling the MCP server knows runs a newer release than it, its instructions say
+so, and so does the first `fling_publish` or `fling_deploy` result of the session on that Fling.
+Claude then suggests the update command (`npm i -g @nearform/fling@latest && fling setup`, then
+restart Claude): inside Claude you never see the CLI's own update line.
+
 The MCP server never prompts:
 
 - **Names.** Without a `name`, `fling_deploy` uses the generated name and fails with suggestions if