flypod 0.16.1 → 0.18.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
 
@@ -191,6 +196,13 @@ With no path, flypod tries these in order and takes the first one that exists
191
196
  dist · build · out · .output/public · .vercel/output/static · public · _site
192
197
  ```
193
198
 
199
+ A candidate with no `index.html` of its own counts when exactly one folder
200
+ inside it has one (Angular's `dist/<app>/browser`). Failing all of them, a
201
+ folder of plain pages (an `index.html` and no `package.json`, `_config.yml` or
202
+ other project file) deploys as it is. A project root is never deployed by
203
+ guesswork: when nothing is found, the error's `fix` names the build command and
204
+ the folder it writes, e.g. ``Run `npm run build`, then `flypod ./dist`.``
205
+
194
206
  The URL is printed alone on **stdout** whenever stdout is not your terminal;
195
207
  everything else goes to stderr. So `URL=$(npx flypod)` and
196
208
  `npx flypod | tee url.txt` both get just the URL, and at a terminal you see it
@@ -220,7 +232,8 @@ out (and listed) when it points outside it, loops, or points nowhere.
220
232
  On flypod.dev a deploy may hold at most 200 files and 10 MB of files (12 MB
221
233
  as an upload: the archive is stored, not compressed, so it is the files plus
222
234
  a few bytes each). flypod checks before uploading and fails with `too_large`,
223
- naming the limit and the largest files. A self-hosted server sets its own
235
+ naming the limit and the largest files, and, when a few files are the
236
+ difference, the `.flypodignore` lines that would leave them out. A self-hosted server sets its own
224
237
  limits (`UPLOAD_MAX_*`) and enforces them itself.
225
238
 
226
239
  To skip the package runner:
@@ -253,13 +266,16 @@ flypod update ./dist # same, with an explicit path
253
266
 
254
267
  Every deploy is a version, identified by the content hash of its files.
255
268
  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.
269
+ nothing to the history — the CLI just reports that version as live. Earlier
270
+ versions stay stored, which is what makes rollback instant — for seven days: a
271
+ version that is not live is deleted seven days after it was deployed, so
272
+ rollback reaches back about a week. The live version lasts as long as the site.
258
273
 
259
274
  **How `update` knows which site.** On the first deploy, flypod records the
260
275
  folder → site mapping in its own config dir (`projects.json`, next to the
261
276
  session — **never written into your repo**). From that folder, `update`,
262
- `versions`, and `rollback` need no flags.
277
+ `versions`, and `rollback` need no flags, and `update` with no path deploys
278
+ the folder the site was last deployed from.
263
279
 
264
280
  To act on a site from anywhere — or from a stateless agent that kept the
265
281
  `site_id` from the deploy output — pass `--site`:
@@ -334,8 +350,12 @@ At a terminal `versions` prints an aligned table with the live version marked:
334
350
  Piped, it prints the same list as tab-separated `version_id created_at live`
335
351
  rows on stdout, with `created_at` as a readable UTC date. `--json` keeps it as
336
352
  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.
353
+ `--json` is supported on every verb for stable, scriptable output: `versions`
354
+ returns `site_id`, `live_version_id`, `versions` (each `version_id` and
355
+ `created_at`), `expires_at`, `timeline` and `next`; `rollback` returns
356
+ `site_id`, `live_version_id` and `url`; `install skill` returns `targets` (each
357
+ `id`, `dir` and `changed`), `files` (each `path` and `status`) and `legacy`, and
358
+ never opens the picker.
339
359
 
340
360
  ## How do I use flypod from an agent or CI?
341
361
 
@@ -370,7 +390,9 @@ serve a site that's broken for visitors, and this array is the only signal that
370
390
  says so. Each entry carries a `code` and a `fix_recipe` naming the change to
371
391
  make — `missing-index` when nothing is served at `/`, `not-spa` when the build
372
392
  ships scripts alongside visible body content, so client-side routing fallback
373
- stays off and deep links will 404 on refresh.
393
+ 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`).
374
396
 
375
397
  `healed` is the other half: problems flypod fixed on your behalf. `spa-fallback`
376
398
  there means it recognised a single-page app, so unknown paths serve `index.html`
@@ -406,23 +428,36 @@ chat, a log, or a pull request, and a `manage_token` cannot be rotated.
406
428
  `--json --verbose` adds the rest: `manage_token` and `claim_token`, `source`,
407
429
  `files`, `bytes`, `elapsed_ms`, `owner_account_id` on an owned deploy, the
408
430
  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`.
431
+ prose. `claim_token` and `owner_account_id` are omitted when they don't apply;
432
+ `expires_in_days` and `expires_at_iso` are `null` once the site is yours, like
433
+ `expires_at`, and `next.keep` is left out then.
434
+
435
+ 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
440
+ site is actually in) plus `history_url` when it is on.
411
441
 
412
442
  **Every failure is JSON too**, on every verb, so `--json` is safe to parse
413
443
  unconditionally:
414
444
 
415
445
  ```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 }
446
+ { "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
447
  ```
418
448
 
419
449
  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
421
- found, or the path given does not exist), `no_files`, `no_site`,
450
+ present, is the literal next step; `status` is the HTTP status when a server
451
+ answered. The codes: `no_build_dir` (no build folder
452
+ found, or the path given does not exist), `no_files`, `no_site` (with a
453
+ `reason` on `update`, `versions` and `rollback`: `never_linked`, `expired`,
454
+ `gone`, or `other_folder` when a folder above or below is the linked one),
422
455
  `not_signed_in`, `unauthorized`, `token_rejected`, `site_gone`,
423
456
  `invalid_upload`, `too_large` (checked before uploading too, naming the limit
424
457
  and the largest files), `blocked`, `challenge_required`, `rate_limited`,
425
- `server_error`, `network` (the server could not be reached, or a proxy or
458
+ `server_error` (a 5xx; `flypod update` has already retried it once, since an
459
+ update is safe to repeat, and an error from flypod itself carries `request_id`
460
+ to quote), `network` (the server could not be reached, or a proxy or
426
461
  firewall in between refused the request), `usage` (bad arguments, including a value flag with
427
462
  no value: `--site needs a value`), `unknown_flag` (naming the closest real flag
428
463
  when there is one), `unknown_command` (a verb that does not exist — a bare word
@@ -446,12 +481,17 @@ anonymous 14-day site.
446
481
  `flypod login --json`: it prints the URL, the confirmation code, and a
447
482
  `device_code`, then exits at once (`interactive_login_required`, exit 2) instead
448
483
  of waiting. Hand the URL and code to the user; once they confirm, finish with
449
- `flypod login --device-code <device_code>` — that polls once and either saves
484
+ `flypod login --device-code <device_code> --json` — that polls once and either saves
450
485
  the session (`{"ok": true, "logged_in": true}`) or reports
451
486
  `authorization_pending` (exit 4) to try again. The flow ends for good with
452
487
  `login_denied` (exit 3, the user said no) or `login_expired` (exit 1, start
453
- again); an interactive `flypod login` that gives up waiting reports
454
- `login_timeout` (exit 4).
488
+ again; also what a code that was already used, or a `user_code` passed in
489
+ place of the `device_code`, answers); an interactive `flypod login` that gives up waiting reports
490
+ `login_timeout` (exit 4). The JSON from `flypod login --json` also carries
491
+ `verification_uri`, `verification_uri_complete` and `user_code` (plus
492
+ `expires_in` and `interval` when the server sends them). After a login,
493
+ `attached` lists the temporary sites it attached and `skipped` the ones it
494
+ could not.
455
495
 
456
496
  Or capture just the URL:
457
497
 
@@ -619,35 +659,49 @@ Deploy flags:
619
659
  | `--json` | Emit the result as JSON on stdout (replaces the pretty output) |
620
660
  | `--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
661
  | `-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 |
662
+ | `--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
663
  | `--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 |
664
+ | `--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
665
  | `-h`, `--help` | Show usage on stdout (JSON under `--json`); never runs the command |
626
666
  | `-v`, `--version` | Print the version |
627
667
 
628
- Targeting flags, on `update` / `versions` / `rollback` / `forget`:
668
+ Targeting flags, on `update` / `versions` / `rollback` / `forget` / `token`:
629
669
 
630
670
  | Flag | Description |
631
671
  |------|-------------|
632
672
  | `--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 |
673
+ | `--token <tok>` | A site's `manage_token`, for anonymous sites on a machine that doesn't remember it (`update`, `versions`, `rollback`) |
634
674
  | `--json` | Stable JSON on stdout |
635
675
  | `-q`, `--quiet` | Minimal output (`update` only) |
676
+ | `--verbose` | The full receipt (`update` only) |
677
+ | `--timeline`, `--no-timeline` | Switch History on or off (`update`, `versions`) |
678
+
679
+ `flypod login` takes `--token <t>`, `--device-code <c>` and `--json`;
680
+ `logout`, `list` and `claim` take only `--json`. Every verb takes `-h` /
681
+ `--help`.
636
682
 
637
683
  ## Environment variables
638
684
 
639
685
  | Variable | Description |
640
686
  |----------|-------------|
641
- | `FLYPOD_TOKEN` | Deploy as your account without logging in (agents / CI). Takes precedence over a saved session |
687
+ | `FLYPOD_TOKEN` | A session token: deploy as your account without logging in (agents / CI). Takes precedence over a saved session |
642
688
  | `DEPLOY_URL` | The deploy server (default: `https://flypod.dev`) |
643
689
  | `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 |
690
+ | `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
691
  | `FLYPOD_SHOW_TOKEN` | Set to `1` to print the site's manage token inline on deploy (off by default) |
646
692
  | `NO_COLOR` | Disable ANSI colors |
647
693
  | `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) |
695
+ | `FLYPOD_TELEMETRY` | `0`, `false`, `off` or `no` turns off the same, for flypod alone |
648
696
 
649
697
  `FLYPOD_API_KEY` is still read as a last-resort fallback for older setups; new
650
- setups should use `FLYPOD_TOKEN`.
698
+ setups should use `FLYPOD_TOKEN`. The old `fk_` API keys are retired and
699
+ flypod no longer accepts them for anything: a deploy that sends one fails with
700
+ `token_rejected`.
701
+
702
+ Which credential a command sends, first match wins: `--token`, then the
703
+ site's own `manage_token` from `projects.json`, then `FLYPOD_TOKEN`, then the
704
+ `flypod login` session, then `FLYPOD_API_KEY`.
651
705
 
652
706
  ## Exit codes
653
707
 
@@ -658,7 +712,7 @@ The exit code follows the failure's `code`, so the table is true for every verb:
658
712
  | `0` | Success |
659
713
  | `1` | Runtime error the caller can act on — no build folder, site gone, upload rejected or blocked |
660
714
  | `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 |
715
+ | `3` | Auth — not signed in, credential refused (`unauthorized`, `token_rejected`), no manage token held (`no_token`), or sign-in denied |
662
716
  | `4` | Retryable — rate limited, server 5xx, network failure, or a sign-in still pending |
663
717
  | `130` | The interactive skill picker was cancelled; nothing was written |
664
718
 
@@ -714,22 +768,29 @@ the static output and host the backend elsewhere.
714
768
 
715
769
  Deployed sites can carry a comment layer, anchored to text rather than
716
770
  coordinates, so notes survive a redeploy. Enabling comments requires an account
717
- session (`flypod login` or `FLYPOD_TOKEN`).
771
+ session (`flypod login` or `FLYPOD_TOKEN`) on a site that account owns. Inside
772
+ a folder you deployed from, `--site` (or the `<site>` positional) can be left
773
+ out.
718
774
 
719
775
  ```sh
720
776
  flypod ./dist --comments --mode passcode # on at deploy time
721
777
  flypod comments enable --site <id> # on an existing site
722
778
  flypod comments mode approved --site <id> # anonymous | passcode | approved
723
779
  flypod comments off --site <id> # disable; existing data is kept
724
- flypod comments list <site> # threads (--json for ND-JSON)
780
+ flypod comments list <site> # threads, one JSON object per line
781
+ flypod comments list <site> --open # or --resolved, --all; --page <p>, --limit N
725
782
  flypod comments show <site> <thread_id> # a thread with its replies
726
783
  flypod comments post <site> --page <p> --target <json> --body <text>
727
784
  flypod comments resolve <site> <thread_id>
728
785
  flypod comments reopen <site> <thread_id>
729
786
  ```
730
787
 
731
- Modes: `anonymous` (anyone can comment), `passcode` (a shared passcode gates
732
- posting), `approved` (comments appear after review).
788
+ Modes: `anonymous` (anyone can comment), `passcode` (a shared passcode, set
789
+ with `--passcode <s>`, gates posting), `approved` (comments appear after the
790
+ owner approves them).
791
+
792
+ `post`, `resolve` and `reopen` refuse a retired `fk_` key before sending
793
+ (`unauthorized`, exit 3).
733
794
 
734
795
  Reviewers need no account in `anonymous` mode, which is the point: ship a
735
796
  preview, collect what came back as JSON, fix, `flypod update`, resolve the
@@ -763,24 +824,58 @@ points the folder at the new site, and flypod keeps the first one's record so
763
824
 
764
825
  ## What does flypod write to disk?
765
826
 
766
- Two files, both in the CLI's own config directory — **never in your repo**:
827
+ Three files, all in the CLI's own config directory — **never in your repo**:
767
828
 
768
829
  | File | What's in it |
769
830
  |------|--------------|
770
831
  | `session.json` | Your session token and the host it belongs to, after `flypod login` |
771
832
  | `projects.json` | The folder → site map, plus the `manage_token` for anonymous sites |
833
+ | `install.json` | A random install id and when it was made (see [Telemetry](#telemetry)); not written when you opt out |
772
834
 
773
835
  Location: `~/Library/Application Support/flypod` (macOS),
774
836
  `$XDG_CONFIG_HOME/flypod` or `~/.config/flypod` (Linux), `%APPDATA%\flypod`
775
- (Windows). Override with `FLYPOD_CONFIG_DIR`. Both are written atomically with
837
+ (Windows). Override with `FLYPOD_CONFIG_DIR`. All are written atomically with
776
838
  mode `0600`. The project registry is self-cleaning: entries for expired sites
777
839
  are pruned on every load, and it's capped at the 64 most recently used.
778
840
 
779
841
  `flypod install skill` is the exception — that command writes agent
780
842
  instruction files into the repo, by design, and tells you every path it touched.
781
843
 
844
+ ## Telemetry
845
+
846
+ The `flypod` CLI counts deploys per install, so flypod.dev can tell one
847
+ person's tenth deploy from ten people's first. What it sends:
848
+
849
+ - **An install id**: 16 random bytes made the first time the CLI talks to a
850
+ server, kept in `install.json`, sent as `x-flypod-install` on the CLI's
851
+ requests. Nothing about your machine or you goes into it.
852
+ - **The CLI version** (`x-flypod-version`).
853
+ - **Which coding agent ran it, and whether CI did**: one word from a fixed
854
+ list (`claude_code`, `codex`, `cursor`, `gemini`, `opencode`, `other` or
855
+ `none`) as `x-flypod-agent`, and `x-flypod-ci: 1` or `0`. The CLI picks the
856
+ word from environment variables the agents set for the commands they run
857
+ (`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.
858
+ - **Failure reports**: when a command fails against flypod.dev, one small
859
+ request to `/telemetry/cli` with the error `code`, the verb, the OS,
860
+ runtime and its major version, and whether a script or agent ran it. For
861
+ `too_large`, `no_files` and `no_build_dir` it adds the upload's shape:
862
+ file count, kilobytes per kind of file (HTML, scripts, images, source
863
+ maps, …), and whether the folder has a `package.json`, a `src/` or a build
864
+ folder (`dist`, `build`, …). For `no_site` it adds which kind (`reason`),
865
+ and for `unauthorized` which kind of credential was refused. Never file
866
+ names, paths, contents or the error text. A report is never printed, gives up after 1.5 s, and is never
867
+ sent to a self-hosted server.
868
+
869
+ The first time an id is made, a terminal run says so in one line.
870
+
871
+ 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()`)
873
+ sends none of this and writes nothing to your home directory.
874
+
782
875
  ## Library API
783
876
 
877
+ ESM-only, one entry point, and runs on Node 18+ and Bun.
878
+
784
879
  ```ts
785
880
  import { collectDist, deploySite, resolveDeployDir } from "flypod";
786
881
 
@@ -803,11 +898,18 @@ console.log(result.url);
803
898
  | `files` | `Record<string, Uint8Array>` | — | File path → bytes |
804
899
  | `baseUrl` | `string` | `https://flypod.dev` | The deploy server |
805
900
  | `apiKey` | `string` | — | Sent as `Authorization: Bearer …`, so the deploy is attributed |
806
- | `source` | `"cli" \| "skill" \| "library"` | `"library"` | Reported as `x-flypod-source` |
901
+ | `source` | `"cli" \| "skill" \| "library" \| "browser" \| "mcp" \| "ci" \| "unknown"` | `FLYPOD_SOURCE`, else `"library"` | Reported as `x-flypod-source` |
807
902
  | `handle` | `(req) => Promise<Response>` | `fetch` | Injectable transport (used in tests) |
808
903
 
809
- Called directly, `deploySite` never reads a saved session or ambient env vars —
810
- pass `apiKey` explicitly if you want an attributed deploy.
904
+ Called directly, `deploySite` never reads a saved session or a credential from
905
+ the environment — pass `apiKey` explicitly if you want an attributed deploy.
906
+ The one environment variable it reads is the `FLYPOD_SOURCE` label, and only
907
+ when `source` is not passed.
908
+
909
+ A refused deploy throws a `DeployError` with `status` (the HTTP status),
910
+ `code` (the server's stable code, such as `rate_limited` or `token_rejected`,
911
+ when it sent one) and `body` (the response verbatim). A network failure throws
912
+ whatever `fetch` threw.
811
913
 
812
914
  Returns a `DeployResult`:
813
915
 
@@ -827,8 +929,10 @@ interface DeployResult {
827
929
  }
828
930
  ```
829
931
 
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
932
+ The `manage_token` authorizes redeploy, rollback, and claim while the site is
933
+ temporary. Once the site belongs to an account the server stops accepting it and
934
+ the account session authorizes instead; deleting a site is account-only either
935
+ way. The CLI stashes it in `projects.json` and you
832
936
  rarely need to handle it yourself, but **the library has no registry**: called
833
937
  directly, `deploySite` hands you the only copy, so if you want to reach that
834
938
  site again, you have to keep it. Treat it and `claim_token` as secrets.
@@ -843,12 +947,30 @@ CLI does (see [What gets uploaded](#what-gets-uploaded)), including those in a
843
947
  ### `collectFiles(path)`
844
948
 
845
949
  The same, plus a report: `{ files, skipped }`, where `skipped` is
846
- `Array<{ path, reason }>` — what was left out and why.
950
+ `Array<{ path, reason }>` — what was left out and why (`reason` is `default`,
951
+ `flypodignore`, `symlink_outside`, `symlink_loop` or `broken_symlink`;
952
+ directories end in `/`). A path that names a single file is read as the only
953
+ file in the site and is never filtered.
847
954
 
848
955
  ### `resolveDeployDir({ cwd?, explicit? })`
849
956
 
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.
957
+ Returns the directory to deploy: `explicit` verbatim if given (it is not
958
+ checked), otherwise the first folder in `BUILD_DIR_CANDIDATES` under `cwd`
959
+ (default `process.cwd()`) that contains an `index.html`; then a candidate with
960
+ exactly one app folder inside that does (`dist/<app>/` or `dist/<app>/browser/`);
961
+ then `cwd` itself when it has an `index.html` and no `package.json` (or other
962
+ project file) and is not the home directory. Throws if none match.
963
+
964
+ ### Constants
965
+
966
+ | Export | Value |
967
+ |--------|-------|
968
+ | `BUILD_DIR_CANDIDATES` | The folders `resolveDeployDir` tries, in order: `dist`, `build`, `out`, `.output/public`, `.vercel/output/static`, `public`, `_site` |
969
+ | `DEFAULT_IGNORES` | The patterns always left out: `.git`, `.hg`, `.svn`, `node_modules`, `.DS_Store`, `Thumbs.db`, `.env`, `.env.*` |
970
+ | `IGNORE_FILE` | `".flypodignore"` |
971
+
972
+ The types `DeployOptions`, `DeployResult`, `DeploySource` (the values `source`
973
+ accepts), `CollectedFiles` and `SkippedPath` are exported too.
852
974
 
853
975
  ## HTTP API
854
976
 
@@ -856,8 +978,10 @@ folder found under `cwd` that contains an `index.html`. Throws if none match.
856
978
  [How do I deploy from a chat app?](#how-do-i-deploy-from-a-chat-app))
857
979
 
858
980
  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.
981
+ directly. Management calls authorize with the site's `manage_token` while the
982
+ site is temporary, and with an account session once it is owned. A bearer token
983
+ on `POST /sites` that the server does not accept fails with `401`
984
+ `token_rejected` rather than deploying anonymously.
861
985
 
862
986
  ```sh
863
987
  # create a site (anonymous — no credentials required)