flypod 0.16.1 → 0.17.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
@@ -143,7 +143,9 @@ flypod install skill --yes # same as --all (-y): never prompt, for script
143
143
 
144
144
  `--cursor`, `--codex`, `--copilot`, `--gemini`, `--windsurf`, `--cline`, and
145
145
  `--roo` remain as aliases for `--agents`; those agents all read
146
- `.agents/skills/` now.
146
+ `.agents/skills/` now. `--print` is the same as `--dry-run`. The installer prints the
147
+ paths it wrote (or would write) on stdout, one per line, and its notes on
148
+ stderr.
147
149
 
148
150
  It's idempotent. Every file inside a skill directory is flypod-owned and
149
151
  rewritten wholesale; files that are already correct are reported as up to date
@@ -170,6 +172,7 @@ earlier version, the command points them out and leaves the removal to you.
170
172
  - [Comments on a deployed site](#comments-on-a-deployed-site)
171
173
  - [Accounts](#accounts)
172
174
  - [What does flypod write to disk?](#what-does-flypod-write-to-disk)
175
+ - [Telemetry](#telemetry)
173
176
  - [Library API](#library-api)
174
177
  - [HTTP API](#http-api)
175
178
 
@@ -184,6 +187,8 @@ npx flypod index.html # a single file
184
187
  npx flypod # auto-detect the build folder
185
188
  ```
186
189
 
190
+ `flypod deploy <path>` is the same command, for callers that always name a verb.
191
+
187
192
  With no path, flypod tries these in order and takes the first one that exists
188
193
  **and contains an `index.html`**:
189
194
 
@@ -253,8 +258,10 @@ flypod update ./dist # same, with an explicit path
253
258
 
254
259
  Every deploy is a version, identified by the content hash of its files.
255
260
  Re-deploying byte-identical content resolves to the **same version id** and adds
256
- nothing to the history — the CLI just reports that version as live. Old versions
257
- are kept, which is what makes rollback instant.
261
+ nothing to the history — the CLI just reports that version as live. Earlier
262
+ versions stay stored, which is what makes rollback instant — for seven days: a
263
+ version that is not live is deleted seven days after it was deployed, so
264
+ rollback reaches back about a week. The live version lasts as long as the site.
258
265
 
259
266
  **How `update` knows which site.** On the first deploy, flypod records the
260
267
  folder → site mapping in its own config dir (`projects.json`, next to the
@@ -334,8 +341,12 @@ At a terminal `versions` prints an aligned table with the live version marked:
334
341
  Piped, it prints the same list as tab-separated `version_id created_at live`
335
342
  rows on stdout, with `created_at` as a readable UTC date. `--json` keeps it as
336
343
  epoch milliseconds, so scripts and agents parse the same value they always did.
337
- `--json` is supported on `update`, `versions`, and `rollback` for stable,
338
- scriptable output.
344
+ `--json` is supported on every verb for stable, scriptable output: `versions`
345
+ returns `site_id`, `live_version_id`, `versions` (each `version_id` and
346
+ `created_at`), `expires_at`, `timeline` and `next`; `rollback` returns
347
+ `site_id`, `live_version_id` and `url`; `install skill` returns `targets` (each
348
+ `id`, `dir` and `changed`), `files` (each `path` and `status`) and `legacy`, and
349
+ never opens the picker.
339
350
 
340
351
  ## How do I use flypod from an agent or CI?
341
352
 
@@ -406,18 +417,26 @@ chat, a log, or a pull request, and a `manage_token` cannot be rotated.
406
417
  `--json --verbose` adds the rest: `manage_token` and `claim_token`, `source`,
407
418
  `files`, `bytes`, `elapsed_ms`, `owner_account_id` on an owned deploy, the
408
419
  expiry restated as `expires_in_days` and `expires_at_iso`, and a `next_note` in
409
- prose. Keys that don't apply are omitted rather than emitted
410
- as `null`.
420
+ prose. `claim_token` and `owner_account_id` are omitted when they don't apply;
421
+ `expires_in_days` and `expires_at_iso` are `null` once the site is yours, like
422
+ `expires_at`, and `next.keep` is left out then.
423
+
424
+ Two more keys appear only when they apply: `replaced_link` (`site_id` and
425
+ `url` of the site this folder pointed at before — a second `flypod` in a
426
+ linked folder makes a new site, and the old one keeps running until it
427
+ expires), and, with `--timeline` / `--no-timeline`, `timeline` (the state the
428
+ site is actually in) plus `history_url` when it is on.
411
429
 
412
430
  **Every failure is JSON too**, on every verb, so `--json` is safe to parse
413
431
  unconditionally:
414
432
 
415
433
  ```json
416
- { "ok": false, "code": "rate_limited", "error": "Too many requests from this network right now.", "fix": "Wait a minute and retry the same command.", "retry_after_s": 30 }
434
+ { "ok": false, "code": "rate_limited", "error": "Too many requests from this network right now.", "fix": "Wait a minute and retry the same command.", "status": 429, "retry_after_s": 30 }
417
435
  ```
418
436
 
419
437
  Branch on `code` — it is stable; `error` is prose and may change; `fix`, when
420
- present, is the literal next step. The codes: `no_build_dir` (no build folder
438
+ present, is the literal next step; `status` is the HTTP status when a server
439
+ answered. The codes: `no_build_dir` (no build folder
421
440
  found, or the path given does not exist), `no_files`, `no_site`,
422
441
  `not_signed_in`, `unauthorized`, `token_rejected`, `site_gone`,
423
442
  `invalid_upload`, `too_large` (checked before uploading too, naming the limit
@@ -451,7 +470,11 @@ the session (`{"ok": true, "logged_in": true}`) or reports
451
470
  `authorization_pending` (exit 4) to try again. The flow ends for good with
452
471
  `login_denied` (exit 3, the user said no) or `login_expired` (exit 1, start
453
472
  again); an interactive `flypod login` that gives up waiting reports
454
- `login_timeout` (exit 4).
473
+ `login_timeout` (exit 4). The JSON from `flypod login --json` also carries
474
+ `verification_uri`, `verification_uri_complete` and `user_code` (plus
475
+ `expires_in` and `interval` when the server sends them). After a login,
476
+ `attached` lists the temporary sites it attached and `skipped` the ones it
477
+ could not.
455
478
 
456
479
  Or capture just the URL:
457
480
 
@@ -619,35 +642,49 @@ Deploy flags:
619
642
  | `--json` | Emit the result as JSON on stdout (replaces the pretty output) |
620
643
  | `--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` |
621
644
  | `-q`, `--quiet` | Print only the URL on stdout, and nothing else |
622
- | `--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` is the same flag |
645
+ | `--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 |
623
646
  | `--comments` | Enable comments on the new site (requires being signed in; otherwise the receipt says `comments_skipped`) |
624
- | `--mode <mode>` | With `--comments`: `anonymous` (default), `passcode`, or `approved`. Anything else is a usage error |
647
+ | `--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 |
625
648
  | `-h`, `--help` | Show usage on stdout (JSON under `--json`); never runs the command |
626
649
  | `-v`, `--version` | Print the version |
627
650
 
628
- Targeting flags, on `update` / `versions` / `rollback` / `forget`:
651
+ Targeting flags, on `update` / `versions` / `rollback` / `forget` / `token`:
629
652
 
630
653
  | Flag | Description |
631
654
  |------|-------------|
632
655
  | `--site <id>` | The site to act on, instead of the folder's remembered site |
633
- | `--token <tok>` | A site's `manage_token`, for anonymous sites on a machine that doesn't remember it |
656
+ | `--token <tok>` | A site's `manage_token`, for anonymous sites on a machine that doesn't remember it (`update`, `versions`, `rollback`) |
634
657
  | `--json` | Stable JSON on stdout |
635
658
  | `-q`, `--quiet` | Minimal output (`update` only) |
659
+ | `--verbose` | The full receipt (`update` only) |
660
+ | `--timeline`, `--no-timeline` | Switch History on or off (`update`, `versions`) |
661
+
662
+ `flypod login` takes `--token <t>`, `--device-code <c>` and `--json`;
663
+ `logout`, `list` and `claim` take only `--json`. Every verb takes `-h` /
664
+ `--help`.
636
665
 
637
666
  ## Environment variables
638
667
 
639
668
  | Variable | Description |
640
669
  |----------|-------------|
641
- | `FLYPOD_TOKEN` | Deploy as your account without logging in (agents / CI). Takes precedence over a saved session |
670
+ | `FLYPOD_TOKEN` | A session token: deploy as your account without logging in (agents / CI). Takes precedence over a saved session |
642
671
  | `DEPLOY_URL` | The deploy server (default: `https://flypod.dev`) |
643
672
  | `FLYPOD_CONFIG_DIR` | Where the CLI keeps its session + folder memory |
644
- | `FLYPOD_SOURCE` | Override how the deploy reports its surface (`cli`, `skill`, `library`). `deploySite()` reads it too when no `source` is passed |
673
+ | `FLYPOD_SOURCE` | Override the surface every request reports in `x-flypod-source` (`cli`, `skill`, `library`, `browser`, `mcp`, `ci`; anything else is recorded as `unknown`). `deploySite()` reads it too when no `source` is passed |
645
674
  | `FLYPOD_SHOW_TOKEN` | Set to `1` to print the site's manage token inline on deploy (off by default) |
646
675
  | `NO_COLOR` | Disable ANSI colors |
647
676
  | `FORCE_COLOR` | Force colors even when stderr is not a TTY |
677
+ | `DO_NOT_TRACK` | Set (to anything but `0` or `false`) to turn off the install id and failure reports. See [Telemetry](#telemetry) |
678
+ | `FLYPOD_TELEMETRY` | `0`, `false`, `off` or `no` turns off the same, for flypod alone |
648
679
 
649
680
  `FLYPOD_API_KEY` is still read as a last-resort fallback for older setups; new
650
- setups should use `FLYPOD_TOKEN`.
681
+ setups should use `FLYPOD_TOKEN`. The old `fk_` API keys are retired and
682
+ flypod no longer accepts them for anything: a deploy that sends one fails with
683
+ `token_rejected`.
684
+
685
+ Which credential a command sends, first match wins: `--token`, then the
686
+ site's own `manage_token` from `projects.json`, then `FLYPOD_TOKEN`, then the
687
+ `flypod login` session, then `FLYPOD_API_KEY`.
651
688
 
652
689
  ## Exit codes
653
690
 
@@ -658,7 +695,7 @@ The exit code follows the failure's `code`, so the table is true for every verb:
658
695
  | `0` | Success |
659
696
  | `1` | Runtime error the caller can act on — no build folder, site gone, upload rejected or blocked |
660
697
  | `2` | Usage error — unknown flag, unknown subcommand, missing argument, or a login that needs a browser (`--json`) |
661
- | `3` | Auth — not signed in, credential refused (`unauthorized`, `token_rejected`), or sign-in denied |
698
+ | `3` | Auth — not signed in, credential refused (`unauthorized`, `token_rejected`), no manage token held (`no_token`), or sign-in denied |
662
699
  | `4` | Retryable — rate limited, server 5xx, network failure, or a sign-in still pending |
663
700
  | `130` | The interactive skill picker was cancelled; nothing was written |
664
701
 
@@ -714,22 +751,29 @@ the static output and host the backend elsewhere.
714
751
 
715
752
  Deployed sites can carry a comment layer, anchored to text rather than
716
753
  coordinates, so notes survive a redeploy. Enabling comments requires an account
717
- session (`flypod login` or `FLYPOD_TOKEN`).
754
+ session (`flypod login` or `FLYPOD_TOKEN`) on a site that account owns. Inside
755
+ a folder you deployed from, `--site` (or the `<site>` positional) can be left
756
+ out.
718
757
 
719
758
  ```sh
720
759
  flypod ./dist --comments --mode passcode # on at deploy time
721
760
  flypod comments enable --site <id> # on an existing site
722
761
  flypod comments mode approved --site <id> # anonymous | passcode | approved
723
762
  flypod comments off --site <id> # disable; existing data is kept
724
- flypod comments list <site> # threads (--json for ND-JSON)
763
+ flypod comments list <site> # threads, one JSON object per line
764
+ flypod comments list <site> --open # or --resolved, --all; --page <p>, --limit N
725
765
  flypod comments show <site> <thread_id> # a thread with its replies
726
766
  flypod comments post <site> --page <p> --target <json> --body <text>
727
767
  flypod comments resolve <site> <thread_id>
728
768
  flypod comments reopen <site> <thread_id>
729
769
  ```
730
770
 
731
- Modes: `anonymous` (anyone can comment), `passcode` (a shared passcode gates
732
- posting), `approved` (comments appear after review).
771
+ Modes: `anonymous` (anyone can comment), `passcode` (a shared passcode, set
772
+ with `--passcode <s>`, gates posting), `approved` (comments appear after the
773
+ owner approves them).
774
+
775
+ `post`, `resolve` and `reopen` refuse a retired `fk_` key before sending
776
+ (`unauthorized`, exit 3).
733
777
 
734
778
  Reviewers need no account in `anonymous` mode, which is the point: ship a
735
779
  preview, collect what came back as JSON, fix, `flypod update`, resolve the
@@ -763,24 +807,52 @@ points the folder at the new site, and flypod keeps the first one's record so
763
807
 
764
808
  ## What does flypod write to disk?
765
809
 
766
- Two files, both in the CLI's own config directory — **never in your repo**:
810
+ Three files, all in the CLI's own config directory — **never in your repo**:
767
811
 
768
812
  | File | What's in it |
769
813
  |------|--------------|
770
814
  | `session.json` | Your session token and the host it belongs to, after `flypod login` |
771
815
  | `projects.json` | The folder → site map, plus the `manage_token` for anonymous sites |
816
+ | `install.json` | A random install id and when it was made (see [Telemetry](#telemetry)); not written when you opt out |
772
817
 
773
818
  Location: `~/Library/Application Support/flypod` (macOS),
774
819
  `$XDG_CONFIG_HOME/flypod` or `~/.config/flypod` (Linux), `%APPDATA%\flypod`
775
- (Windows). Override with `FLYPOD_CONFIG_DIR`. Both are written atomically with
820
+ (Windows). Override with `FLYPOD_CONFIG_DIR`. All are written atomically with
776
821
  mode `0600`. The project registry is self-cleaning: entries for expired sites
777
822
  are pruned on every load, and it's capped at the 64 most recently used.
778
823
 
779
824
  `flypod install skill` is the exception — that command writes agent
780
825
  instruction files into the repo, by design, and tells you every path it touched.
781
826
 
827
+ ## Telemetry
828
+
829
+ The `flypod` CLI counts deploys per install, so flypod.dev can tell one
830
+ person's tenth deploy from ten people's first. What it sends:
831
+
832
+ - **An install id**: 16 random bytes made the first time the CLI talks to a
833
+ server, kept in `install.json`, sent as `x-flypod-install` on the CLI's
834
+ requests. Nothing about your machine or you goes into it.
835
+ - **The CLI version** (`x-flypod-version`).
836
+ - **Failure reports**: when a command fails against flypod.dev, one small
837
+ request to `/telemetry/cli` with the error `code`, the verb, the OS,
838
+ runtime and its major version, and whether a script or agent ran it. For
839
+ `too_large`, `no_files` and `no_build_dir` it adds the upload's shape:
840
+ file count, kilobytes per kind of file (HTML, scripts, images, source
841
+ maps, …), and whether the folder has a `package.json`, a `src/` or a build
842
+ folder (`dist`, `build`, …). Never file names, paths, contents or the
843
+ error text. A report is never printed, gives up after 1.5 s, and is never
844
+ sent to a self-hosted server.
845
+
846
+ The first time an id is made, a terminal run says so in one line.
847
+
848
+ Turn all of it off with `DO_NOT_TRACK=1` (or `FLYPOD_TELEMETRY=0`): no id is
849
+ made or sent, and no failure reports go out. The library (`deploySite()`)
850
+ sends none of this and writes nothing to your home directory.
851
+
782
852
  ## Library API
783
853
 
854
+ ESM-only, one entry point, and runs on Node 18+ and Bun.
855
+
784
856
  ```ts
785
857
  import { collectDist, deploySite, resolveDeployDir } from "flypod";
786
858
 
@@ -803,11 +875,18 @@ console.log(result.url);
803
875
  | `files` | `Record<string, Uint8Array>` | — | File path → bytes |
804
876
  | `baseUrl` | `string` | `https://flypod.dev` | The deploy server |
805
877
  | `apiKey` | `string` | — | Sent as `Authorization: Bearer …`, so the deploy is attributed |
806
- | `source` | `"cli" \| "skill" \| "library"` | `"library"` | Reported as `x-flypod-source` |
878
+ | `source` | `"cli" \| "skill" \| "library" \| "browser" \| "mcp" \| "ci" \| "unknown"` | `FLYPOD_SOURCE`, else `"library"` | Reported as `x-flypod-source` |
807
879
  | `handle` | `(req) => Promise<Response>` | `fetch` | Injectable transport (used in tests) |
808
880
 
809
- Called directly, `deploySite` never reads a saved session or ambient env vars —
810
- pass `apiKey` explicitly if you want an attributed deploy.
881
+ Called directly, `deploySite` never reads a saved session or a credential from
882
+ the environment — pass `apiKey` explicitly if you want an attributed deploy.
883
+ The one environment variable it reads is the `FLYPOD_SOURCE` label, and only
884
+ when `source` is not passed.
885
+
886
+ A refused deploy throws a `DeployError` with `status` (the HTTP status),
887
+ `code` (the server's stable code, such as `rate_limited` or `token_rejected`,
888
+ when it sent one) and `body` (the response verbatim). A network failure throws
889
+ whatever `fetch` threw.
811
890
 
812
891
  Returns a `DeployResult`:
813
892
 
@@ -827,8 +906,10 @@ interface DeployResult {
827
906
  }
828
907
  ```
829
908
 
830
- The `manage_token` authorizes redeploy, rollback, and claim — deleting a site is
831
- account-only, so it can't do that. The CLI stashes it in `projects.json` and you
909
+ The `manage_token` authorizes redeploy, rollback, and claim while the site is
910
+ temporary. Once the site belongs to an account the server stops accepting it and
911
+ the account session authorizes instead; deleting a site is account-only either
912
+ way. The CLI stashes it in `projects.json` and you
832
913
  rarely need to handle it yourself, but **the library has no registry**: called
833
914
  directly, `deploySite` hands you the only copy, so if you want to reach that
834
915
  site again, you have to keep it. Treat it and `claim_token` as secrets.
@@ -843,12 +924,27 @@ CLI does (see [What gets uploaded](#what-gets-uploaded)), including those in a
843
924
  ### `collectFiles(path)`
844
925
 
845
926
  The same, plus a report: `{ files, skipped }`, where `skipped` is
846
- `Array<{ path, reason }>` — what was left out and why.
927
+ `Array<{ path, reason }>` — what was left out and why (`reason` is `default`,
928
+ `flypodignore`, `symlink_outside`, `symlink_loop` or `broken_symlink`;
929
+ directories end in `/`). A path that names a single file is read as the only
930
+ file in the site and is never filtered.
847
931
 
848
932
  ### `resolveDeployDir({ cwd?, explicit? })`
849
933
 
850
- Returns the directory to deploy: `explicit` if given, otherwise the first build
851
- folder found under `cwd` that contains an `index.html`. Throws if none match.
934
+ Returns the directory to deploy: `explicit` verbatim if given (it is not
935
+ checked), otherwise the first folder in `BUILD_DIR_CANDIDATES` under `cwd`
936
+ (default `process.cwd()`) that contains an `index.html`. Throws if none match.
937
+
938
+ ### Constants
939
+
940
+ | Export | Value |
941
+ |--------|-------|
942
+ | `BUILD_DIR_CANDIDATES` | The folders `resolveDeployDir` tries, in order: `dist`, `build`, `out`, `.output/public`, `.vercel/output/static`, `public`, `_site` |
943
+ | `DEFAULT_IGNORES` | The patterns always left out: `.git`, `.hg`, `.svn`, `node_modules`, `.DS_Store`, `Thumbs.db`, `.env`, `.env.*` |
944
+ | `IGNORE_FILE` | `".flypodignore"` |
945
+
946
+ The types `DeployOptions`, `DeployResult`, `DeploySource` (the values `source`
947
+ accepts), `CollectedFiles` and `SkippedPath` are exported too.
852
948
 
853
949
  ## HTTP API
854
950
 
@@ -856,8 +952,10 @@ folder found under `cwd` that contains an `index.html`. Throws if none match.
856
952
  [How do I deploy from a chat app?](#how-do-i-deploy-from-a-chat-app))
857
953
 
858
954
  The CLI wraps these. Reach for raw HTTP only when scripting against the API
859
- directly. Management calls authorize with the site's `manage_token`, or with an
860
- account session for owned sites.
955
+ directly. Management calls authorize with the site's `manage_token` while the
956
+ site is temporary, and with an account session once it is owned. A bearer token
957
+ on `POST /sites` that the server does not accept fails with `401`
958
+ `token_rejected` rather than deploying anonymously.
861
959
 
862
960
  ```sh
863
961
  # create a site (anonymous — no credentials required)