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 +63 -27
- package/dist/bin/deploy.js +247 -43
- package/dist/{cli-4d5fkx95.js → cli-qtqg73w5.js} +434 -231
- package/dist/src/cli/agent-guide.d.ts +16 -0
- package/dist/src/cli/commands.d.ts +25 -1
- package/dist/src/cli/errors.d.ts +4 -1
- package/dist/src/cli/install-id.d.ts +16 -6
- package/dist/src/cli/invoked-via.d.ts +6 -0
- package/dist/src/cli/pending-login.d.ts +17 -0
- package/dist/src/cli-error-codes.d.ts +8 -0
- package/dist/src/cli.js +1 -1
- package/dist/src/client-meta.d.ts +33 -0
- package/package.json +1 -1
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`
|
|
216
|
-
|
|
217
|
-
`flypod`
|
|
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
|
|
249
|
-
existing site and points the live URL at it
|
|
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
|
|
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`
|
|
395
|
-
(
|
|
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
|
|
420
|
-
|
|
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
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
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;
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
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
|
-
| `--
|
|
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
|
|
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:
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|