flypod 0.18.0 → 0.19.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -212,9 +212,11 @@ Every command's output uses the same few shapes: a `✓` line for what
212
212
  happened, the URL on a line of its own, a small grid of next steps, `!` for
213
213
  something to look at, and `✗` with the fix underneath when it did not work.
214
214
 
215
- `flypod` always creates a **new site**. To ship changes to a site you already
216
- made, use [`flypod update`](#how-do-i-ship-a-change-to-the-same-site) — not
217
- `flypod` again.
215
+ The first `flypod` in a folder creates a **new site**. Every later `flypod` in
216
+ that folder updates the same site, like
217
+ [`flypod update`](#how-do-i-ship-a-change-to-the-same-site): same URL, new
218
+ version. To make a separate site from a folder that already has one, run
219
+ `flypod --new`.
218
220
 
219
221
  ### What gets uploaded
220
222
 
@@ -245,15 +247,20 @@ flypod ./dist
245
247
 
246
248
  ## How do I ship a change to the same site?
247
249
 
248
- Run `flypod update` from the same folder. It adds a new **version** to the
249
- existing site and points the live URL at it — the URL doesn't change.
250
+ Run `flypod update` (or plain `flypod` again) from the same folder. It adds a
251
+ new **version** to the existing site and points the live URL at it; the URL
252
+ doesn't change.
250
253
 
251
254
  ```sh
252
255
  flypod ./dist # v1 → new site, prints the URL
253
256
  flypod update # ship changes → v2 (now live, same URL)
254
- flypod update ./dist # same, with an explicit path
257
+ flypod ./dist # same: this folder already has a site, so it updates it
258
+ flypod --new # a separate new site; the earlier one stays live
255
259
  ```
256
260
 
261
+ If the folder's site is gone (deleted, or expired), plain `flypod` makes a new
262
+ one, as if the folder had never deployed.
263
+
257
264
  ```
258
265
  ✓ Updated · version 8f1a0c2e is live
259
266
 
@@ -369,6 +376,7 @@ npx flypod ./dist --json
369
376
  ```json
370
377
  {
371
378
  "ok": true,
379
+ "action": "created",
372
380
  "url": "https://a3f1c2d4e5b60789.flypod.page",
373
381
  "site_id": "a3f1c2d4e5b60789",
374
382
  "version_id": "8f1a0c2e44b7d913",
@@ -380,19 +388,23 @@ npx flypod ./dist --json
380
388
  "update": "flypod update",
381
389
  "versions": "flypod versions",
382
390
  "rollback": "flypod rollback",
383
- "keep": "flypod login"
391
+ "keep": "flypod login --json"
384
392
  }
385
393
  }
386
394
  ```
387
395
 
396
+ `action` is `"created"` on a folder's first deploy and `"updated"` when
397
+ `flypod` ran in a folder that already had a site: that run is an update, and
398
+ its receipt is the `flypod update` receipt.
399
+
388
400
  **Read `warnings` before you report success.** A deploy can exit 0 and still
389
401
  serve a site that's broken for visitors, and this array is the only signal that
390
402
  says so. Each entry carries a `code` and a `fix_recipe` naming the change to
391
403
  make — `missing-index` when nothing is served at `/`, `not-spa` when the build
392
404
  ships scripts alongside visible body content, so client-side routing fallback
393
405
  stays off and deep links will 404 on refresh, and `new-site-in-linked-folder`
394
- when `flypod` ran in a folder that already had a site and so made a second one
395
- (the deploy is live; ship later changes with `flypod update`).
406
+ when `flypod --new` made a separate site from a folder that already had one
407
+ (both are live; this folder now updates the new one).
396
408
 
397
409
  `healed` is the other half: problems flypod fixed on your behalf. `spa-fallback`
398
410
  there means it recognised a single-page app, so unknown paths serve `index.html`
@@ -416,8 +428,10 @@ uploaded.
416
428
 
417
429
  `expires_at` is epoch **milliseconds** while the site is temporary, and `null`
418
430
  once it's yours. `next` holds the literal commands for what comes after;
419
- `next.update` is the one that matters, because running `flypod` again makes a
420
- second site. `link_saved` says whether `flypod update` will work from this
431
+ `next.update` is the one that matters: it ships a change to this same URL
432
+ (in a linked folder plain `flypod` does too). `next.keep`, while the site
433
+ expires, is `flypod login --json`: see
434
+ [signing in from an agent](#how-do-i-use-flypod-from-an-agent-or-ci). `link_saved` says whether `flypod update` will work from this
421
435
  folder with no flags; when it is `false` the `next` commands carry
422
436
  `--site <id>`, and the receipt includes `manage_token`, because nobody else is
423
437
  holding it.
@@ -433,10 +447,10 @@ prose. `claim_token` and `owner_account_id` are omitted when they don't apply;
433
447
  `expires_at`, and `next.keep` is left out then.
434
448
 
435
449
  Two more keys appear only when they apply: `replaced_link` (`site_id` and
436
- `url` of the site this folder pointed at before — a second `flypod` in a
437
- linked folder makes a new site, and the old one keeps running until it
438
- expires; the receipt's `warnings` then carries `new-site-in-linked-folder`,
439
- and `-q` says so in one line on stderr), and, with `--timeline` / `--no-timeline`, `timeline` (the state the
450
+ `url` of the site this folder pointed at before, only after `flypod --new`
451
+ in a linked folder; the old site keeps running until it expires, the
452
+ receipt's `warnings` then carries `new-site-in-linked-folder`, and `-q` says
453
+ so in one line on stderr), and, with `--timeline` / `--no-timeline`, `timeline` (the state the
440
454
  site is actually in) plus `history_url` when it is on.
441
455
 
442
456
  **Every failure is JSON too**, on every verb, so `--json` is safe to parse
@@ -480,10 +494,14 @@ anonymous 14-day site.
480
494
  **Signing in from an agent.** `flypod login` needs a browser, so an agent runs
481
495
  `flypod login --json`: it prints the URL, the confirmation code, and a
482
496
  `device_code`, then exits at once (`interactive_login_required`, exit 2) instead
483
- of waiting. Hand the URL and code to the user; once they confirm, finish with
484
- `flypod login --device-code <device_code> --json` — that polls once and either saves
485
- the session (`{"ok": true, "logged_in": true}`) or reports
486
- `authorization_pending` (exit 4) to try again. The flow ends for good with
497
+ of waiting. Hand the URL and code to the user; that is all. Once they confirm, the next
498
+ flypod command of any kind (a deploy, `flypod list`, anything) finishes
499
+ signing in by itself and keeps every site on the machine, as `flypod login`
500
+ does, then runs signed in. To finish at once instead, run
501
+ `flypod login --device-code <device_code> --json`: it waits up to 25 seconds
502
+ for the confirmation and either saves the session
503
+ (`{"ok": true, "logged_in": true}`) or reports `authorization_pending` (exit 4)
504
+ to try again. The flow ends for good with
487
505
  `login_denied` (exit 3, the user said no) or `login_expired` (exit 1, start
488
506
  again; also what a code that was already used, or a `user_code` passed in
489
507
  place of the `device_code`, answers); an interactive `flypod login` that gives up waiting reports
@@ -660,7 +678,8 @@ Deploy flags:
660
678
  | `--verbose` | More of the same receipt. In a terminal: the rollback and history commands, plus the site id, version id and source folder. With `--json`: also tokens, counts, timing. Also on `flypod update` |
661
679
  | `-q`, `--quiet` | Print only the URL on stdout, and nothing else |
662
680
  | `--timeline`, `--no-timeline` | Turn History on or off: the chip on the site's pages, an address per version, and the compare page. Also on `flypod update`, and on `flypod versions` to switch it without deploying. `--history` / `--no-history` are the same flags |
663
- | `--comments` | Enable comments on the new site (requires being signed in; otherwise the receipt says `comments_skipped`) |
681
+ | `--new` | Make a separate new site, even though this folder already has one. The earlier site stays live, and this folder then updates the new one. The receipt carries `replaced_link` |
682
+ | `--comments` | Enable comments on the site (requires being signed in; otherwise the receipt says `comments_skipped`) |
664
683
  | `--mode <mode>` | With `--comments`: `anonymous` (default), `passcode`, or `approved` (the older names `open`, `review` and `members` are still accepted). Anything else is a usage error |
665
684
  | `-h`, `--help` | Show usage on stdout (JSON under `--json`); never runs the command |
666
685
  | `-v`, `--version` | Print the version |
@@ -691,7 +710,7 @@ Targeting flags, on `update` / `versions` / `rollback` / `forget` / `token`:
691
710
  | `FLYPOD_SHOW_TOKEN` | Set to `1` to print the site's manage token inline on deploy (off by default) |
692
711
  | `NO_COLOR` | Disable ANSI colors |
693
712
  | `FORCE_COLOR` | Force colors even when stderr is not a TTY |
694
- | `DO_NOT_TRACK` | Set (to anything but `0` or `false`) to turn off the install id, the agent and CI words, and failure reports. See [Telemetry](#telemetry) |
713
+ | `DO_NOT_TRACK` | Set (to anything but `0` or `false`) to turn off the install id, the agent, CI, launch and agent-instructions words, and failure reports. See [Telemetry](#telemetry) |
695
714
  | `FLYPOD_TELEMETRY` | `0`, `false`, `off` or `no` turns off the same, for flypod alone |
696
715
 
697
716
  `FLYPOD_API_KEY` is still read as a last-resort fallback for older setups; new
@@ -806,7 +825,7 @@ flypod login # approve this CLI in your browser (device flow)
806
825
  flypod login --token <t> # check a session token, then save it; no browser
807
826
  flypod list # your sites (JSON on stdout)
808
827
  flypod claim <id> <token> # attach one anonymous deploy by its claim token
809
- flypod logout # forget the local session
828
+ flypod logout # forget the local session (and any sign-in still waiting)
810
829
  ```
811
830
 
812
831
  `flypod login` does two things at once: it attaches every anonymous site this
@@ -818,18 +837,19 @@ does not accept fails with `token_rejected` (exit 3), and a server it cannot
818
837
  reach with `network` (exit 4). Nothing is saved in either case.
819
838
 
820
839
  "Every site this machine remembers" includes a site whose folder you have
821
- since deployed a different site from: running `flypod` twice in one folder
822
- points the folder at the new site, and flypod keeps the first one's record so
840
+ since deployed a different site from: `flypod --new` in a folder that
841
+ already has a site points the folder at the new site, and flypod keeps the first one's record so
823
842
  `flypod login` still keeps it and `--site <id>` still reaches it.
824
843
 
825
844
  ## What does flypod write to disk?
826
845
 
827
- Three files, all in the CLI's own config directory — **never in your repo**:
846
+ These files, all in the CLI's own config directory, **never in your repo**:
828
847
 
829
848
  | File | What's in it |
830
849
  |------|--------------|
831
850
  | `session.json` | Your session token and the host it belongs to, after `flypod login` |
832
851
  | `projects.json` | The folder → site map, plus the `manage_token` for anonymous sites |
852
+ | `pending-login.json` | Only while a `flypod login --json` waits for its person: the device code, so the next command can finish the sign-in. Not a credential; worthless after ten minutes |
833
853
  | `install.json` | A random install id and when it was made (see [Telemetry](#telemetry)); not written when you opt out |
834
854
 
835
855
  Location: `~/Library/Application Support/flypod` (macOS),
@@ -855,6 +875,20 @@ person's tenth deploy from ten people's first. What it sends:
855
875
  `none`) as `x-flypod-agent`, and `x-flypod-ci: 1` or `0`. The CLI picks the
856
876
  word from environment variables the agents set for the commands they run
857
877
  (`AI_AGENT`, `CLAUDECODE`, `CLAUDE_CODE_ENTRYPOINT`, `CURSOR_AGENT`, `GEMINI_CLI`, `CODEX_SANDBOX`, `CODEX_SANDBOX_NETWORK_DISABLED`, `CODEX_THREAD_ID`, `CODEX_MANAGED_BY_NPM`) and from `CI` / `GITHUB_ACTIONS`; the variables' values are never sent.
878
+ - **How it was launched**: one word (`npx`, `bunx`, `pnpm_dlx`, `yarn_dlx`,
879
+ `script`, `local`, `global` or `other`) as `x-flypod-invoked-via`, from the
880
+ shape of the CLI's own script path (a package manager's cache, a
881
+ `node_modules`, a global prefix) and the variables package managers set
882
+ (`npm_lifecycle_event`, `npm_command`, `npm_config_user_agent`,
883
+ `npm_execpath`). Never the path or the values.
884
+ - **Whether the project's agent instructions name flypod**: one word
885
+ (`skill`, `agents_md`, `claude_md`, `cursor_rules`, `copilot`, `gemini_md`
886
+ or `none`) as `x-flypod-agent-guide`. The CLI reads the start (32 KB) of
887
+ `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, `.cursor/rules/*`,
888
+ `.github/copilot-instructions.md` and `GEMINI.md` in the folder it runs in
889
+ and its parents up to the repository root, never the home directory, and
890
+ sends only which kind of file contains the word `flypod`. Never a file's
891
+ content, name or path.
858
892
  - **Failure reports**: when a command fails against flypod.dev, one small
859
893
  request to `/telemetry/cli` with the error `code`, the verb, the OS,
860
894
  runtime and its major version, and whether a script or agent ran it. For
@@ -862,14 +896,16 @@ person's tenth deploy from ten people's first. What it sends:
862
896
  file count, kilobytes per kind of file (HTML, scripts, images, source
863
897
  maps, …), and whether the folder has a `package.json`, a `src/` or a build
864
898
  folder (`dist`, `build`, …). For `no_site` it adds which kind (`reason`),
865
- and for `unauthorized` which kind of credential was refused. Never file
899
+ and for `unauthorized` which kind of credential was refused, whether this
900
+ machine knew the site, and whether it was named by the folder's link or
901
+ `--site`. Never file
866
902
  names, paths, contents or the error text. A report is never printed, gives up after 1.5 s, and is never
867
903
  sent to a self-hosted server.
868
904
 
869
905
  The first time an id is made, a terminal run says so in one line.
870
906
 
871
907
  Turn all of it off with `DO_NOT_TRACK=1` (or `FLYPOD_TELEMETRY=0`): no id is
872
- made or sent, no agent or CI word is sent, and no failure reports go out. The library (`deploySite()`)
908
+ made or sent, no agent, CI, launch or agent-instructions word is sent, and no failure reports go out. The library (`deploySite()`)
873
909
  sends none of this and writes nothing to your home directory.
874
910
 
875
911
  ## Library API