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 +165 -41
- package/dist/bin/deploy.js +877 -383
- package/dist/{cli-8h0vc7g2.js → cli-4d5fkx95.js} +842 -83
- package/dist/src/api-error.d.ts +4 -0
- package/dist/src/cli/agent-env.d.ts +5 -0
- package/dist/src/cli/build-hint.d.ts +13 -0
- package/dist/src/cli/client.d.ts +15 -3
- package/dist/src/cli/commands.d.ts +4 -0
- package/dist/src/cli/errors.d.ts +105 -1
- package/dist/src/cli/install-id.d.ts +42 -0
- package/dist/src/cli/limits.d.ts +45 -1
- package/dist/src/cli/projects.d.ts +51 -3
- package/dist/src/cli/receipt.d.ts +18 -0
- package/dist/src/cli/skill.d.ts +26 -5
- package/dist/src/cli/source.d.ts +3 -1
- package/dist/src/cli/telemetry.d.ts +38 -0
- package/dist/src/cli-error-codes.d.ts +28 -0
- package/dist/src/cli.d.ts +16 -3
- package/dist/src/cli.js +1 -1
- package/dist/src/client-meta.d.ts +50 -0
- package/dist/src/deploy-source.d.ts +20 -0
- package/dist/src/ingest-error.d.ts +58 -1
- package/dist/src/upload-shape.d.ts +57 -0
- package/package.json +4 -1
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
|
|
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.
|
|
257
|
-
|
|
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
|
|
338
|
-
|
|
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.
|
|
410
|
-
|
|
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
|
|
421
|
-
|
|
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
|
|
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
|
|
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
|
|
454
|
-
`
|
|
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`
|
|
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
|
|
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` |
|
|
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
|
|
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
|
|
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
|
|
732
|
-
posting), `approved` (comments appear after
|
|
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
|
-
|
|
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`.
|
|
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
|
|
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
|
|
831
|
-
|
|
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
|
|
851
|
-
|
|
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
|
|
860
|
-
account session
|
|
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)
|