@nearform/fling 0.1.2 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+## Unreleased
+
+## 0.3.0
+
+**Breaking: no default server.** The CLI works with any Fling deployment, so it no longer has one
+built in.
+
+- `fling login <url>` (or `fling setup <url>`) signs in to the Fling at that address. The CLI
+  reads the server's `/.well-known/fling` (its name, sites domain, sign-in method) and remembers
+  both in `~/.fling/config.json`; later commands, and `fling login` without a URL, use them.
+  `FLING_URL` and `--server` still override it.
+- Upgrading from 0.2: if you logged in with 0.2, nothing changes; the server you logged in to is
+  kept, and its metadata is fetched the first time it is needed. A config without a server (a new
+  machine, or a key set by hand) fails with `No Fling server set — run fling login <url> …`
+  instead of assuming a server.
+- Site URLs shown before a deploy come from the server's metadata instead of being guessed from
+  the server URL.
+- The local MCP server (`fling mcp`, the Claude Desktop extension) names your Fling and its sites
+  domain in its tool descriptions. The extension's **Fling server** setting has no built-in
+  default; the copy a Fling serves at `/downloads/fling.mcpb` has its address filled in.
+- Comments: `fling comments`, `fling comment` (and `--reply`), `fling resolve`, `fling uncomment`;
+  the local MCP server gains `fling_comments_list`, `fling_comment_add`, `fling_comment_resolve`
+  and `fling_comment_delete` on an instance with the `comments` capability.
+- On an instance with comments, a deploy (`fling deploy`, and the MCP server's `fling_deploy` and
+  `fling_publish`) also gives the review page, the link to share for feedback: in the output box,
+  as `reviewUrl` in `--json` and in the MCP result, where it leads.
+
+## 0.2.0
+
+`fling setup`, a new look, and help by default.

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Nearform
+Copyright (c) 2026 Clifton Cunningham
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,14 +1,18 @@
 # @nearform/fling
 
-Fling a folder of static files at [fling.labs.nearform.com](https://fling.labs.nearform.com) and
-get a stable link back:
+Fling a folder of static files at your Fling server and get a stable link back:
 
 ```
-https://<name>.fling.labs.nearform.com
+https://<name>.<your sites domain>
 ```
 
-Site names are one global namespace, first come first served. Sites are private to signed-in Nearformers by default. Share links make them viewable by anyone
-who has the link.
+Site names are one global namespace per server, first come first served. Sites are private to
+people signed in to that Fling by default. Share links make them viewable by anyone who has the
+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).
 
 ## Install
 
@@ -20,31 +24,48 @@ npm install -g @nearform/fling   # then: fling …
 npx @nearform/fling …
 ```
 
-## Log in
+## Set up
 
 ```sh
-fling login
+fling setup https://fling.example.com   # your Fling's address; later runs can leave it out
 ```
 
-This opens your browser for Nearform Google sign-in and stores an API key in
-`~/.fling/config.json` (mode 0600). `fling whoami` shows who you are, and `fling logout` removes the
-key. For CI, set `FLING_API_KEY` instead.
+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
+   stored in `~/.fling/config.json` (mode 0600). This is skipped if you're already signed in.
+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`).
+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.
+
+On a terminal it asks before steps 2 and 3. With `--yes` it does them without asking.
+
+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>`.
+`fling whoami` shows who you are, and `fling logout` removes the key (and keeps the server). For CI,
+set `FLING_URL` and `FLING_API_KEY` instead.
 
 ## Deploy
 
 ```sh
 npm run build
-fling ./dist                        # name generated from the project, e.g. rocketpod-docs; you confirm it
-fling ./dist --name my-app          # → https://my-app.fling.labs.nearform.com
-fling ./dist --name my-app --spa    # client-side routing: unknown paths serve index.html
-fling ./dist --public               # no sign-in needed to view
-fling ./dist --yes                  # never prompt (CI): use the generated name as is
-fling                               # deploys the current folder
-fling "Pitch Deck.html"             # a single page, served as index.html → pitch-deck
-fling site.zip                      # a zip of a site: extracted, a single top folder unwrapped
-fling diagram.svg                   # any other file, next to a generated page that shows it
+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 --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
+fling deploy site.zip                      # a zip of a site: extracted, a single top folder unwrapped
+fling deploy diagram.svg                   # any other file, next to a generated page that shows it
 ```
 
+`fling <path>` is short for `fling deploy <path>` when the path exists, so `fling ./dist` works.
+An existing path wins over a command of the same name. Bare `fling` prints help.
+
 What you can fling:
 
 - **A folder**, as is.
@@ -57,14 +78,8 @@ What you can fling:
 A file's default site name comes from its name, without the extension or a browser's ` (1)`
 duplicate suffix: `Pitch Deck (1).html` → `pitch-deck`. Folders use the naming rules below.
 
-**Files by name.** If the path doesn't exist where you are, Fling looks for it by name, newest
-first, in Downloads (`FLING_DOWNLOADS_DIR` if set; on Linux your XDG download folder), Desktop,
-`~/Documents/Claude`, `~/Claude` and Claude Desktop's output folders, and says where it found it:
-
-```
-$ fling Pitch-Deck.html
-fling Found in Downloads: /Users/me/Downloads/Pitch-Deck.html
-```
+The path must exist where you give it. The CLI doesn't look for files elsewhere (the MCP server
+does; see below).
 
 - Re-fling to update. Identical content is a no-op, and content you deployed before is restored
   instantly without uploading.
@@ -118,7 +133,7 @@ Without `--name`, the name is generated from the folder, never from your user na
 In a terminal, Fling checks the generated name and asks before deploying:
 
 ```
-fling Site name: rocketpod-docs → https://rocketpod-docs.fling.labs.nearform.com/  (new)
+fling Site name: rocketpod-docs → https://rocketpod-docs.sites.example.com/  (new)
 Use "rocketpod-docs"? [Y/n or type another name]
 ```
 
@@ -154,11 +169,27 @@ and a taken name fails (exit 1) with suggestions rather than picking another nam
 | `fling archive <name>` / `fling unarchive <name>` | take offline and keep the files, or bring back |
 | `fling rm <name> [--yes]` | delete permanently |
 
-Global options: `--json` prints machine-readable output, and `--server <url>` points at another
-server. Exit codes are `0` ok, `1` error, `2` not logged in and `3` forbidden.
+## Comments
+
+People review a site on its review page (`<your Fling>/review/<name>`, the **Review** button on the
+sites page): the site beside its comments. Anyone signed in who can open the site can comment; the
+CLI reads and writes the same threads. On a Fling with comments, `fling deploy` (and the MCP
+server's `fling_deploy` / `fling_publish`) also prints the review page as the link to share for
+feedback (`reviewUrl` in `--json`); reviewers sign in to use it.
+
+| Command | |
+|---|---|
+| `fling comments <name> [--path <page>] [--all]` | open threads (with replies) by page; `--all` adds resolved ones |
+| `fling comment <name> "text" [--path <page>]` | comment on a page (default `/`) |
+| `fling comment <name> "text" --reply <id>` | reply to a thread |
+| `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 |
+
+Global options: `--json` prints machine-readable output, and `--server <url>` points one command at
+another server. Exit codes are `0` ok, `1` error, `2` not logged in and `3` forbidden.
 
 Environment: `FLING_API_KEY`, `FLING_URL`, `FLING_CONFIG_DIR`, `FLING_DEBUG`, `FLING_DOWNLOADS_DIR`
-(where files given by name are looked for first), `FLING_NO_WAIT=1` (after a deploy or a new share
+(where the MCP server looks for files given by name first), `FLING_NO_WAIT=1` (after a deploy or a new share
 link, don't wait the few seconds it takes to reach every edge).
 
 ## Claude Code plugin and MCP
@@ -166,12 +197,20 @@ link, don't wait the few seconds it takes to reach every edge).
 The Fling plugin gives Claude a `fling` skill plus an MCP server (`fling mcp`), so you can say
 "fling the dist folder and give me a share link":
 
+```sh
+fling setup
+```
+
+Or install it by hand in Claude Code:
+
 ```
 /plugin marketplace add nearform/fling
 /plugin install fling@fling
 ```
 
-Log in once with `fling login` (or `npx @nearform/fling login` if it is not installed). The MCP server reuses that login.
+Log in once with `fling login <url>` (or `npx @nearform/fling login <url>` if it is not installed).
+The MCP server reuses that login, and its tool descriptions name your Fling and where its sites
+live.
 
 The MCP tools:
 
@@ -201,20 +240,21 @@ For Claude Desktop (including Cowork), install the one-click extension. It runs
 on your computer, so Claude can fling files you downloaded or that Claude Desktop saved, by name,
 without uploading anything from Claude's sandbox.
 
-1. Download [fling.mcpb](https://fling.labs.nearform.com/downloads/fling.mcpb).
+1. Download `fling.mcpb` from your Fling (Get started → Download, or `https://<your Fling>/downloads/fling.mcpb`).
 2. Double-click it, or drag it into Claude Desktop, or go to **Settings → Extensions → Advanced
    settings → Install Extension…** and pick the file.
-3. Optional settings: **Fling server** (default `https://fling.labs.nearform.com`) and **Downloads
-   folder** (default `~/Downloads`).
+3. Optional settings: **Fling server** (filled in with the Fling you downloaded it from; empty means
+   the one the CLI is logged in to) and **Downloads folder** (default `~/Downloads`).
 4. Ask Claude to "fling Pitch Deck.html from my Downloads". If you're not signed in, Claude calls
    `fling_login` and your browser opens. The extension and the CLI share the login in
    `~/.fling/config.json`.
 
 It needs Node.js 20 or later, which Claude Desktop provides, on macOS or Windows.
 
-Build it with `pnpm --filter @nearform/fling build:mcpb`. That bundles `src/mcp-entry.ts` and every
-dependency into one file, then validates and packs `mcpb/manifest.json` into `dist/fling.mcpb`.
-CI publishes it at `/downloads/fling.mcpb`.
+Build it with `pnpm --filter ./apps/cli build:mcpb`. That bundles `src/mcp-entry.ts` and every
+dependency into one file, then validates and packs `mcpb/manifest.json` into `dist/fling.mcpb`
+(`FLING_MCPB_SERVER_URL` sets the **Fling server** default). A deploy publishes it at
+`/downloads/fling.mcpb`.
 
 To use the MCP server in another client, run it over stdio:
 
@@ -227,7 +267,7 @@ To use the MCP server in another client, run it over stdio:
 From the repo root:
 
 ```sh
-pnpm cli --server http://localhost:3001 login   # against `pnpm dev`
-pnpm --filter @nearform/fling test
-pnpm --filter @nearform/fling build             # → dist/cli.js
+pnpm cli login http://localhost:47101   # against `pnpm dev`
+pnpm --filter ./apps/cli test
+pnpm --filter ./apps/cli build         # → dist/cli.js
 ```