@nearform/fling 0.8.0 → 0.10.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>`.
@@ -94,7 +145,9 @@ What you can fling:
 - **A single `.html`/`.htm` file**, served as the site's `index.html`.
 - **A `.zip`**: extracted (paths that would escape the folder are refused), `__MACOSX/` and dotfiles
   skipped (dotfiles such as `.env` are listed), and a single top-level folder unwrapped.
-- **Any other file** (`.pdf`, `.svg`, `.png`, `.md`…), served next to a small generated `index.html`
+- **A single Markdown file** (`.md`, `.markdown`), on a Fling that renders Markdown (the
+  `markdown` capability): its rendered page is the site's home page.
+- **Any other file** (`.pdf`, `.svg`, `.png`…), served next to a small generated `index.html`
   that shows it (images, PDF, video, audio) or links to it.
 
 A file's default site name comes from its name, without the extension or a browser's ` (1)`
@@ -105,21 +158,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.
+- **Publish one folder of a site as its Path** with `--path` (and `--name`): `fling deploy ./plan
+  --name payments-plans --path PAY-412` serves the plan at `https://payments-plans.<sites
+  domain>/PAY-412/`. A Path is one top-level folder with its own versions, rollback, owners and
+  publishers; publishing it never touches the rest of the site or its other Paths, so teammates
+  publishing different Paths never collide. The first publish makes the Path, with you as its
+  owner. `--path` takes one folder: nested folders (`reports/2026`) are refused, so publish them as
+  part of their top-level folder. A folder pulled with `fling pull --path` deploys back to its
+  Path. On a Fling without path publishing (`pathPublish`) the CLI refuses rather than replace the
+  whole site. See [Paths](#paths).
 - **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
+  `--path <folder>` pulls one of the site's Paths, its files at the top of `dir`; `--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
@@ -201,15 +256,15 @@ 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, with who published each version and, for a path publish, the folder (PATH) |
+| `fling info <name>` / `fling versions <name> [--path <folder>]` | details and version history, with who published each version; `--path`: a Path's own versions |
 | `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 files <name> [versionId] [--path <folder>]` | the files in the live version (or an earlier one), or a Path's |
+| `fling rollback <name> <versionId> [--path <folder>]` | serve an earlier version (of the site, or of one Path) |
 | `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 (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 owners <name> [--add <emails>] [--remove <emails>] [--set <emails>] [--group <slugs>] [--remove-group <slugs>] [--path <folder>]` | who owns a site (or a Path), or change it |
+| `fling publishers <name> [--add …] [--remove …] [--set …] [--group …] [--remove-group …] [--path <folder>]` | who publishes a site (or a Path) 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 |
 
@@ -287,6 +342,46 @@ admin for an admin's view), and `fling info` its Owners, Publishers and You. As
 commands print `{ name, role, owners, publishers }`, each list `{ emails: [{ email, known, guest?
 }], groups: [{ slug, name, size }] }`.
 
+### Paths
+
+A **Path** is a top-level folder of a site published on its own, such as one plan per ticket on a
+team's site: `fling deploy ./plan --name payments-plans --path PAY-412`. Each Path has its own
+versions, rollback, owners and publishers, and is served at `<site>/<folder>/`. Who can open it is
+the site's. Its owners and publishers, and the site's owners, can publish it, roll it back and
+change it; the site's publishers can make new Paths. On a Fling with Paths (the `paths`
+capability):
+
+```sh
+fling paths payments-plans                        # its Paths: folder, title, version, state, can you publish, updated
+fling versions payments-plans --path PAY-412      # the Path's own versions (* = live)
+fling files payments-plans --path PAY-412         # the files of its live version (or give a version id)
+fling rollback payments-plans <versionId> --path PAY-412   # roll back only the Path
+fling owners payments-plans --path PAY-412 --add cat@example.com
+fling publishers payments-plans --path PAY-412 --add bob@example.com
+fling paths archive payments-plans PAY-412        # take it off the site (404), keep its versions; `paths unarchive` brings it back
+fling paths delete payments-plans PAY-412         # delete it and its versions (asks first unless --yes)
+fling pull payments-plans --path PAY-412          # its files, to change and deploy back to the Path
+```
+
+**The home page.** A site's home page (its root `index.html`) can list its Paths, three ways:
+
+- **Default**: with no `index.html` of its own, the site's home page is a listing of its live
+  Paths. A site whose first publish is a Path gets one. Nothing to do.
+- **Custom**: your own `index.html` with a Paths block, which Fling fills with the live Paths
+  whenever one changes (and serves as JSON at `/_fling-paths.json`). `fling paths init [dir]
+  --template plans|docs|reports|minimal [--title T]` writes a starter (it never replaces an
+  `index.html` without `--force`); adapt it, keeping the block, check it with `fling paths check
+  [dir|file]` (errors exit 1, warnings are printed), then deploy the folder as the site root,
+  without `--path`. The block is the bare marker `<!-- fling:paths -->` (Fling's default list,
+  styled by your page) or a template, `<!-- fling:paths sort=updated --> <a href="{{href}}">{{title}}</a>
+  <!-- fling:empty --> None yet. <!-- /fling:paths -->`, whose item repeats per Path with
+  `{{href}} {{folder}} {{title}} {{updated}} {{date}} {{version}}`. Options: `sort=updated|oldest|folder|folder-desc`,
+  `nocontrols`, `nostyle`; `<!-- fling:paths-controls -->` places the search and sort controls.
+- **None**: an `index.html` without a Paths block lists no Paths, and a deploy says so.
+
+With `--json`, `fling paths` prints `{ name, paths: [{ folder, title, url, currentVersionId,
+archived, owners?, publishers?, canPublish, createdAt, updatedAt }] }`.
+
 ### Groups
 
 A group is a named list of people, such as a team, that anyone signed in can use in a site's
@@ -346,8 +441,10 @@ fling responses my-app --format csv -o labels.csv          # the export: json, j
 - `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.
+- Without the file, deploying a whole site removes its forms. A pulled folder keeps them, unless it
+  was pulled with a `fling.forms.json` you have since deleted. Forms are the site's: a `--path`
+  deploy leaves them as they are and refuses a folder with `fling.forms.json`. Deploy the forms with
+  the site's root, with `paths` patterns that reach the Path's pages (`PAY-412/**`).
 - `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.
@@ -382,7 +479,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
 
@@ -422,14 +520,14 @@ 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). `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
+  name (looked up like the CLI does). `sitePath` (with `name`) publishes it as that Path of the
+  site, the rest untouched, 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; `path` publishes them into that folder of the site;
+  definition as the remote connector's tool; `path` publishes them as that Path 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,
@@ -439,6 +537,12 @@ 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_paths` (a site's Paths, and what its home page does with them) where a Fling has Paths,
+  and `fling_paths_template` and `fling_paths_check` (a starter home page with a Paths block, and
+  its check), which need no Fling. `fling_info`, `fling_files` and `fling_rollback` take `path` to
+  act on one Path.
 - `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, the forms tools when it has forms
@@ -454,6 +558,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