flypod 0.7.0 → 0.8.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 +425 -187
- package/dist/bin/deploy.js +142 -399
- package/dist/{cli-j9rxpfdv.js → cli-g2wb2hxm.js} +621 -14
- package/dist/src/cli/client.d.ts +13 -1
- package/dist/src/cli/commands.d.ts +68 -0
- package/dist/src/cli/projects.d.ts +35 -0
- package/dist/src/cli/skill.d.ts +135 -0
- package/dist/src/cli/source.d.ts +7 -0
- package/dist/src/cli.d.ts +18 -0
- package/dist/src/cli.js +1 -1
- package/dist/src/deploy-source.d.ts +20 -0
- package/package.json +4 -8
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
// src/cli.ts
|
|
2
|
-
import { readdir, readFile as
|
|
3
|
-
import { join as
|
|
2
|
+
import { readdir, readFile as readFile3, stat as stat2 } from "node:fs/promises";
|
|
3
|
+
import { join as join3, relative } from "node:path";
|
|
4
4
|
|
|
5
5
|
// ../../node_modules/.bun/fflate@0.8.3/node_modules/fflate/esm/index.mjs
|
|
6
6
|
import { createRequire } from "module";
|
|
@@ -645,6 +645,14 @@ function zipSync(data, opts) {
|
|
|
645
645
|
return out;
|
|
646
646
|
}
|
|
647
647
|
|
|
648
|
+
// src/deploy-source.ts
|
|
649
|
+
var SOURCE_HEADER = "x-flypod-source";
|
|
650
|
+
var DEPLOY_SOURCES = ["cli", "browser", "library", "skill", "unknown"];
|
|
651
|
+
function coerceSource(value) {
|
|
652
|
+
const normalized = (value ?? "").trim().toLowerCase();
|
|
653
|
+
return DEPLOY_SOURCES.includes(normalized) ? normalized : "unknown";
|
|
654
|
+
}
|
|
655
|
+
|
|
648
656
|
// src/cli/session.ts
|
|
649
657
|
import { readFile, unlink } from "node:fs/promises";
|
|
650
658
|
|
|
@@ -708,6 +716,603 @@ async function clearSession(env) {
|
|
|
708
716
|
}
|
|
709
717
|
}
|
|
710
718
|
|
|
719
|
+
// src/cli/skill.ts
|
|
720
|
+
import { mkdir as mkdir2, readFile as readFile2, stat, writeFile as writeFile2 } from "node:fs/promises";
|
|
721
|
+
import { homedir as homedir2 } from "node:os";
|
|
722
|
+
import { dirname as dirname2, join as join2 } from "node:path";
|
|
723
|
+
var SKILL_NAME = "flypod";
|
|
724
|
+
var SKILL_DESCRIPTION = "Deploy a folder of static files or Markdown to a live, public URL anyone can open — no account, no config. " + "Use it when the user asks to deploy, publish, or share something built; " + "when a build has just finished and someone else needs to look at it; " + "when a report, research write-up, or set of Markdown notes should become a browsable site instead of a file; " + "or when a screenshot or a local dev server will not do because the recipient must open it themselves. " + "Static output only — flypod serves files, and does not run a server or build them.";
|
|
725
|
+
function yamlScalar(value) {
|
|
726
|
+
return `'${value.replaceAll("'", "''")}'`;
|
|
727
|
+
}
|
|
728
|
+
var versionsReference = {
|
|
729
|
+
file: "reference/updates-and-versions.md",
|
|
730
|
+
when: "shipping a change without forking the site, or listing and rolling back versions",
|
|
731
|
+
body: () => `# Updates, versions, and rollback
|
|
732
|
+
|
|
733
|
+
Every command here acts on a site that already exists, so none of them forks it.
|
|
734
|
+
All take \`--json\`.
|
|
735
|
+
|
|
736
|
+
\`\`\`sh
|
|
737
|
+
flypod update # ship this folder as a new version
|
|
738
|
+
flypod update ./dist # same, with an explicit path
|
|
739
|
+
flypod versions # every version, newest first, live one marked
|
|
740
|
+
flypod rollback # put the previous version back
|
|
741
|
+
flypod rollback <version> # roll back to a version id, or a prefix of one
|
|
742
|
+
\`\`\`
|
|
743
|
+
|
|
744
|
+
## How flypod knows which site
|
|
745
|
+
|
|
746
|
+
flypod remembers which folder maps to which site, in its own config directory
|
|
747
|
+
under your home — never in the repo, so there is nothing to \`.gitignore\` and
|
|
748
|
+
nothing to commit. From the folder you deployed, these need no id and no flags.
|
|
749
|
+
|
|
750
|
+
\`FLYPOD_CONFIG_DIR\` relocates that memory, which is how you isolate CI runs.
|
|
751
|
+
|
|
752
|
+
## When the folder memory isn't there
|
|
753
|
+
|
|
754
|
+
Stateless, in a different directory, or holding a \`site_id\` from an earlier
|
|
755
|
+
deploy? Target the site:
|
|
756
|
+
|
|
757
|
+
\`\`\`sh
|
|
758
|
+
flypod update --site <site_id> ./dist
|
|
759
|
+
flypod versions --site <site_id>
|
|
760
|
+
flypod rollback --site <site_id> <version_id>
|
|
761
|
+
flypod forget [--site <site_id>] # drop the folder→site memory
|
|
762
|
+
\`\`\`
|
|
763
|
+
|
|
764
|
+
Sites you own authorize with your login. A **temporary** site acted on from a
|
|
765
|
+
machine that does not remember it authorizes with its manage token:
|
|
766
|
+
|
|
767
|
+
\`\`\`sh
|
|
768
|
+
flypod update --site <site_id> --token <manage_token> ./dist
|
|
769
|
+
\`\`\`
|
|
770
|
+
|
|
771
|
+
\`flypod token [--site <id>]\` prints that token on stdout for a site this machine
|
|
772
|
+
remembers — the one case that needs the plaintext. Treat it like a password: it
|
|
773
|
+
authorizes updates, rollbacks, and claims, and it cannot be rotated.
|
|
774
|
+
|
|
775
|
+
## Versions are content-addressed
|
|
776
|
+
|
|
777
|
+
A version id is a hash of the files, so deploying byte-identical content again
|
|
778
|
+
is a no-op: same hash, same version, no new entry in the history. A redundant
|
|
779
|
+
\`flypod update\` is free, and needs no guard.
|
|
780
|
+
|
|
781
|
+
## Typical loop
|
|
782
|
+
|
|
783
|
+
\`\`\`sh
|
|
784
|
+
npm run build && npx flypod ./dist --json # first deploy, note the url
|
|
785
|
+
# … edit, rebuild …
|
|
786
|
+
npm run build && npx flypod update --json # same url, new content
|
|
787
|
+
npx flypod versions --json # confirm what's live
|
|
788
|
+
npx flypod rollback # undo a bad ship
|
|
789
|
+
\`\`\`
|
|
790
|
+
`
|
|
791
|
+
};
|
|
792
|
+
var markdownReference = {
|
|
793
|
+
file: "reference/publishing-markdown.md",
|
|
794
|
+
when: "publishing Markdown — a report, research notes, a changelog, docs",
|
|
795
|
+
body: () => `# Publishing Markdown with flypod
|
|
796
|
+
|
|
797
|
+
flypod renders Markdown into a styled, browsable site. You do not need a static
|
|
798
|
+
site generator, a theme, or a build step — deploy the \`.md\` files themselves.
|
|
799
|
+
|
|
800
|
+
This is the fastest path from "I wrote a report" to "here is a link."
|
|
801
|
+
|
|
802
|
+
\`\`\`sh
|
|
803
|
+
npx flypod ./report.md --json # one document
|
|
804
|
+
npx flypod ./notes --json # a folder of documents
|
|
805
|
+
\`\`\`
|
|
806
|
+
|
|
807
|
+
## When it triggers
|
|
808
|
+
|
|
809
|
+
Markdown rendering kicks in when **both** are true of the files you deploy:
|
|
810
|
+
|
|
811
|
+
1. There is **no \`index.html\`** at the root of the deploy, and
|
|
812
|
+
2. at least one file ends in \`.md\`, \`.markdown\`, or \`.mdx\`.
|
|
813
|
+
|
|
814
|
+
That condition is deliberate: a real static site that happens to ship a stray
|
|
815
|
+
\`README.md\` is never hijacked. If you want files served untouched instead,
|
|
816
|
+
include an \`index.html\`.
|
|
817
|
+
|
|
818
|
+
## What you get
|
|
819
|
+
|
|
820
|
+
- **One HTML page per document.** \`guide.md\` is served at \`/guide.html\`.
|
|
821
|
+
- **A home page.** \`README.md\` or \`index.md\` becomes \`/\`. If you deploy exactly
|
|
822
|
+
one document, that document becomes the home page whatever it is called.
|
|
823
|
+
- **Navigation** across every document, with the home doc first and the rest
|
|
824
|
+
alphabetical.
|
|
825
|
+
- **A title per page,** taken from the first \`#\` heading, falling back to a
|
|
826
|
+
title-cased version of the filename.
|
|
827
|
+
- **Light and dark themes,** applied before first paint so there is no flash.
|
|
828
|
+
- **Sanitized HTML.** Inline \`<script>\` tags, \`on*\` event attributes, and
|
|
829
|
+
\`javascript:\` links are stripped from the rendered output. Interactive content
|
|
830
|
+
belongs in a built static site, deployed as HTML.
|
|
831
|
+
|
|
832
|
+
## Agents get the Markdown back
|
|
833
|
+
|
|
834
|
+
The original \`.md\` sources are preserved and served through HTTP content
|
|
835
|
+
negotiation on the *same* URL. A browser gets the styled HTML; a client that
|
|
836
|
+
asks for Markdown gets the source:
|
|
837
|
+
|
|
838
|
+
\`\`\`sh
|
|
839
|
+
curl -H 'Accept: text/markdown' https://ab12cd34.flypod.dev/guide.html
|
|
840
|
+
\`\`\`
|
|
841
|
+
|
|
842
|
+
Known agent and crawler user-agents also get Markdown when they express no media
|
|
843
|
+
preference. An explicit preference for HTML always wins, so a real browser is
|
|
844
|
+
never handed raw Markdown.
|
|
845
|
+
|
|
846
|
+
This matters when you are the one reading the site back later: fetch it with
|
|
847
|
+
\`Accept: text/markdown\` and you get clean source instead of parsing HTML.
|
|
848
|
+
|
|
849
|
+
## Good uses
|
|
850
|
+
|
|
851
|
+
- A research write-up or analysis the user asked for, published instead of pasted.
|
|
852
|
+
- A changelog, migration guide, or RFC that needs review from someone without a
|
|
853
|
+
checkout.
|
|
854
|
+
- Meeting notes or a status report that should have a URL rather than an attachment.
|
|
855
|
+
- Documentation for a small project, without adopting a docs framework.
|
|
856
|
+
|
|
857
|
+
Pair it with comments (\`reference/comments.md\`) when the reader should be able
|
|
858
|
+
to respond in place.
|
|
859
|
+
`
|
|
860
|
+
};
|
|
861
|
+
var commentsReference = {
|
|
862
|
+
file: "reference/comments.md",
|
|
863
|
+
when: "collecting feedback on a preview, or reading reviewer comments back",
|
|
864
|
+
body: () => `# Comments — feedback on a deployed site
|
|
865
|
+
|
|
866
|
+
flypod can attach a commenting layer to a site, so a reviewer opens the URL and
|
|
867
|
+
leaves comments anchored to the page. You can then read those comments back as
|
|
868
|
+
JSON and act on them. That closes the loop: ship a preview, collect feedback,
|
|
869
|
+
fix, re-ship — without leaving the terminal.
|
|
870
|
+
|
|
871
|
+
## Turning comments on
|
|
872
|
+
|
|
873
|
+
At deploy time:
|
|
874
|
+
|
|
875
|
+
\`\`\`sh
|
|
876
|
+
npx flypod ./dist --comments --json # mode: anonymous
|
|
877
|
+
npx flypod ./dist --comments --mode approved --json
|
|
878
|
+
\`\`\`
|
|
879
|
+
|
|
880
|
+
On a site that already exists:
|
|
881
|
+
|
|
882
|
+
\`\`\`sh
|
|
883
|
+
flypod comments enable --site <site_id> [--mode <mode>]
|
|
884
|
+
flypod comments mode <mode> --site <site_id> [--passcode <s>]
|
|
885
|
+
flypod comments off --site <site_id> # disable; existing data is preserved
|
|
886
|
+
\`\`\`
|
|
887
|
+
|
|
888
|
+
## Modes
|
|
889
|
+
|
|
890
|
+
| Mode | Who can comment |
|
|
891
|
+
| --- | --- |
|
|
892
|
+
| \`anonymous\` | anyone with the link, no sign-in — best for quick previews |
|
|
893
|
+
| \`passcode\` | anyone holding the passcode you set with \`--passcode\` |
|
|
894
|
+
| \`approved\` | only people you have approved — best for anything semi-public |
|
|
895
|
+
|
|
896
|
+
Default when you pass \`--comments\` with no mode: \`anonymous\`.
|
|
897
|
+
|
|
898
|
+
## Reading feedback
|
|
899
|
+
|
|
900
|
+
\`\`\`sh
|
|
901
|
+
flypod comments list <site_id> --json # ND-JSON: one thread per line
|
|
902
|
+
flypod comments list <site_id> --open --json # only unresolved threads
|
|
903
|
+
flypod comments list <site_id> --page /pricing.html # threads on one page
|
|
904
|
+
flypod comments show <site_id> <thread_id> # one thread with its replies
|
|
905
|
+
\`\`\`
|
|
906
|
+
|
|
907
|
+
\`list\` writes one JSON object per line, so it streams and pipes. \`--json\` only
|
|
908
|
+
suppresses the human-readable count on stderr; the thread objects go to stdout
|
|
909
|
+
either way.
|
|
910
|
+
|
|
911
|
+
## Replying and closing out
|
|
912
|
+
|
|
913
|
+
\`\`\`sh
|
|
914
|
+
flypod comments post <site_id> --page <path> --target <json> --body <text>
|
|
915
|
+
flypod comments resolve <site_id> <thread_id>
|
|
916
|
+
flypod comments reopen <site_id> <thread_id>
|
|
917
|
+
\`\`\`
|
|
918
|
+
|
|
919
|
+
## Authorization
|
|
920
|
+
|
|
921
|
+
Read verbs follow the site's own policy. **Write verbs — \`post\`, \`resolve\`,
|
|
922
|
+
\`reopen\`, and the \`enable\`/\`mode\`/\`off\` verbs — need an account session or an
|
|
923
|
+
agent token.** Run \`flypod login\`, or set \`FLYPOD_TOKEN\`. A deploy-only key (one
|
|
924
|
+
starting \`fk_\`) is rejected up front with exit code 3; it authorizes deploys and
|
|
925
|
+
nothing else. \`reference/troubleshooting.md\` has the full exit-code table.
|
|
926
|
+
|
|
927
|
+
## The review loop
|
|
928
|
+
|
|
929
|
+
\`\`\`sh
|
|
930
|
+
npx flypod ./dist --comments --json # ship a preview, share the url
|
|
931
|
+
flypod comments list <site_id> --open --json # collect what came back
|
|
932
|
+
# … make the fixes …
|
|
933
|
+
npx flypod update ./dist # same url, updated content
|
|
934
|
+
flypod comments resolve <site_id> <thread_id>
|
|
935
|
+
\`\`\`
|
|
936
|
+
`
|
|
937
|
+
};
|
|
938
|
+
var troubleshootingReference = {
|
|
939
|
+
file: "reference/troubleshooting.md",
|
|
940
|
+
when: "a deploy failed or the site looks wrong, or you need exit codes, CI setup, env vars",
|
|
941
|
+
body: () => `# Troubleshooting and environment
|
|
942
|
+
|
|
943
|
+
## Exit codes
|
|
944
|
+
|
|
945
|
+
| Code | Meaning |
|
|
946
|
+
| --- | --- |
|
|
947
|
+
| \`0\` | success |
|
|
948
|
+
| \`1\` | runtime error — no build folder, network failure, deploy rejected |
|
|
949
|
+
| \`2\` | usage error — unknown flag or bad arguments |
|
|
950
|
+
| \`3\` | \`flypod comments\` only: not signed in, or the token cannot write comments |
|
|
951
|
+
| \`4\` | \`flypod comments\` only: server error (5xx), so a retry is reasonable |
|
|
952
|
+
|
|
953
|
+
With \`--json\`, failures print \`{"ok": false, "error": "…"}\` on stdout, so you can
|
|
954
|
+
branch on the payload instead of scraping stderr.
|
|
955
|
+
|
|
956
|
+
## "No build output folder found"
|
|
957
|
+
|
|
958
|
+
flypod looked for \`dist\`, \`build\`, \`out\`, \`.output/public\`,
|
|
959
|
+
\`.vercel/output/static\`, \`public\`, \`_site\` — each of which must contain an
|
|
960
|
+
\`index.html\` — and found none. Either the project has not been built yet, or the
|
|
961
|
+
output lives somewhere else. Build it, then pass the path explicitly:
|
|
962
|
+
|
|
963
|
+
\`\`\`sh
|
|
964
|
+
npm run build && npx flypod ./path/to/output --json
|
|
965
|
+
\`\`\`
|
|
966
|
+
|
|
967
|
+
## The deploy succeeded but the site looks wrong
|
|
968
|
+
|
|
969
|
+
Check the \`warnings\` array in the \`--json\` output before you report success.
|
|
970
|
+
Each warning has a \`code\` and a \`fix_recipe\` naming the change to make.
|
|
971
|
+
|
|
972
|
+
- \`missing-index\` — nothing is served at \`/\`. Name the entry file \`index.html\`.
|
|
973
|
+
- \`not-spa\` — the page ships scripts but also has visible body content, so
|
|
974
|
+
client-side routing fallback stays off and deep links will 404 on refresh.
|
|
975
|
+
|
|
976
|
+
\`healed\` lists what flypod fixed on your behalf. \`spa-fallback\` there means it
|
|
977
|
+
recognised a single-page app, so unknown paths serve \`index.html\` and
|
|
978
|
+
client-side routing works without configuration.
|
|
979
|
+
|
|
980
|
+
## Blank page, broken assets
|
|
981
|
+
|
|
982
|
+
Almost always absolute paths that assume a domain root, or a build configured
|
|
983
|
+
for a subpath. Rebuild with relative asset paths, then \`flypod update\`.
|
|
984
|
+
|
|
985
|
+
## Agents and CI
|
|
986
|
+
|
|
987
|
+
Set a session token in the environment and every deploy is attributed to the
|
|
988
|
+
account, with no browser and no interactive login:
|
|
989
|
+
|
|
990
|
+
\`\`\`sh
|
|
991
|
+
URL=$(FLYPOD_TOKEN=$TOKEN npx flypod ./dist -q)
|
|
992
|
+
\`\`\`
|
|
993
|
+
|
|
994
|
+
\`-q\` prints the URL and nothing else, which keeps the token out of the build log
|
|
995
|
+
it would otherwise outlive.
|
|
996
|
+
|
|
997
|
+
| Variable | Effect |
|
|
998
|
+
| --- | --- |
|
|
999
|
+
| \`FLYPOD_TOKEN\` | Deploy as your account without logging in (agents / CI) |
|
|
1000
|
+
| \`DEPLOY_URL\` | Point at a different flypod server (default \`https://flypod.dev\`) |
|
|
1001
|
+
| \`FLYPOD_CONFIG_DIR\` | Relocate the session + folder→site memory |
|
|
1002
|
+
|
|
1003
|
+
## Getting the full command surface
|
|
1004
|
+
|
|
1005
|
+
\`flypod --help\` is authoritative and current; so is \`--help\` on any subcommand
|
|
1006
|
+
(\`update\`, \`versions\`, \`rollback\`, \`forget\`, \`token\`, \`login\`). Read it rather
|
|
1007
|
+
than guessing at a flag.
|
|
1008
|
+
`
|
|
1009
|
+
};
|
|
1010
|
+
var REFERENCES = [
|
|
1011
|
+
versionsReference,
|
|
1012
|
+
markdownReference,
|
|
1013
|
+
commentsReference,
|
|
1014
|
+
troubleshootingReference
|
|
1015
|
+
];
|
|
1016
|
+
function entryBody() {
|
|
1017
|
+
return `flypod turns a folder into a live, public URL with one command. You bring the
|
|
1018
|
+
files; flypod serves them.
|
|
1019
|
+
|
|
1020
|
+
## Deploy
|
|
1021
|
+
|
|
1022
|
+
1. Build first, if the project has a build — flypod serves files, it does not
|
|
1023
|
+
make them. You want a folder whose contents *are* the finished site.
|
|
1024
|
+
2. Deploy it:
|
|
1025
|
+
|
|
1026
|
+
\`\`\`sh
|
|
1027
|
+
npx flypod ./dist --json
|
|
1028
|
+
\`\`\`
|
|
1029
|
+
|
|
1030
|
+
3. Read \`url\` from the JSON and give it to the user.
|
|
1031
|
+
|
|
1032
|
+
**Done when** the user has the URL, and \`warnings\` is empty or you have told
|
|
1033
|
+
them what is in it.
|
|
1034
|
+
|
|
1035
|
+
Omit the path and flypod auto-detects a build folder, trying \`dist\`, \`build\`,
|
|
1036
|
+
\`out\`, \`.output/public\`, \`.vercel/output/static\`, \`public\`, \`_site\` — each of
|
|
1037
|
+
which must hold an \`index.html\`. Pass the path whenever you know it.
|
|
1038
|
+
|
|
1039
|
+
A single file deploys too: \`flypod report.html\`. For several, deploy the folder.
|
|
1040
|
+
|
|
1041
|
+
No \`flypod\` binary? \`npx flypod ...\` downloads and runs it on the fly, and that
|
|
1042
|
+
is the normal path rather than a fallback. To install once: \`npm install -g flypod\`.
|
|
1043
|
+
|
|
1044
|
+
## The result
|
|
1045
|
+
|
|
1046
|
+
\`\`\`json
|
|
1047
|
+
{
|
|
1048
|
+
"ok": true,
|
|
1049
|
+
"url": "https://ab12cd34.flypod.dev",
|
|
1050
|
+
"site_id": "ab12cd34",
|
|
1051
|
+
"version_id": "…",
|
|
1052
|
+
"expires_at": 1782929906088,
|
|
1053
|
+
"files": 12,
|
|
1054
|
+
"bytes": 1234567,
|
|
1055
|
+
"elapsed_ms": 812,
|
|
1056
|
+
"healed": ["spa-fallback"],
|
|
1057
|
+
"warnings": []
|
|
1058
|
+
}
|
|
1059
|
+
\`\`\`
|
|
1060
|
+
|
|
1061
|
+
- \`url\` — the live site. Give it to the user.
|
|
1062
|
+
- \`warnings\` — problems that survived the deploy, each with a \`code\` and a
|
|
1063
|
+
\`fix_recipe\` naming the change to make. A deploy exits 0 and still serves a
|
|
1064
|
+
broken site; this array is how you find out before the user does.
|
|
1065
|
+
- \`healed\` — problems flypod fixed for you, e.g. \`spa-fallback\`.
|
|
1066
|
+
- \`site_id\` — names the site for \`--site <id>\` from any other folder.
|
|
1067
|
+
- \`expires_at\` — epoch **milliseconds** while the site is temporary, \`null\` once
|
|
1068
|
+
it belongs to an account.
|
|
1069
|
+
- \`manage_token\` / \`claim_token\` — secrets, on a first temporary deploy. The CLI
|
|
1070
|
+
has already saved what it needs, keyed by the folder you deployed from, so
|
|
1071
|
+
these want no action from you. Keep them out of chat, commits, logs, and PR
|
|
1072
|
+
descriptions.
|
|
1073
|
+
|
|
1074
|
+
\`-q\` prints the URL alone, for a shell variable: \`URL=$(npx flypod ./dist -q)\`.
|
|
1075
|
+
|
|
1076
|
+
## Temporary, then yours
|
|
1077
|
+
|
|
1078
|
+
A deploy with no account is **temporary** and expires in **14 days** — right for
|
|
1079
|
+
previews, demos, and throwaways. \`flypod login\` makes every temporary site this
|
|
1080
|
+
machine deployed **yours**: no expiry, listed by \`flypod list\`.
|
|
1081
|
+
|
|
1082
|
+
Because login claims them all at once and not just the last one, the honest
|
|
1083
|
+
advice is "deploy now, log in whenever you want to keep these." Raise it when
|
|
1084
|
+
the user will still want the site next week, and let it go otherwise. \`flypod
|
|
1085
|
+
login\` is how a site is kept — the tokens above are never the answer.
|
|
1086
|
+
|
|
1087
|
+
For agents and CI, set a session token and every deploy is attributed to the
|
|
1088
|
+
account from the start, with no browser:
|
|
1089
|
+
|
|
1090
|
+
\`\`\`sh
|
|
1091
|
+
FLYPOD_TOKEN=<session-token> npx flypod ./dist --json
|
|
1092
|
+
\`\`\`
|
|
1093
|
+
|
|
1094
|
+
## Shipping a change
|
|
1095
|
+
|
|
1096
|
+
A second \`flypod\` **forks** the site: a new site on a new URL, while the link
|
|
1097
|
+
you already gave the user quietly goes stale. \`flypod update\` adds a version to
|
|
1098
|
+
the site you already made, and the URL holds.
|
|
1099
|
+
|
|
1100
|
+
\`\`\`sh
|
|
1101
|
+
flypod update ./dist
|
|
1102
|
+
\`\`\`
|
|
1103
|
+
|
|
1104
|
+
## What flypod serves
|
|
1105
|
+
|
|
1106
|
+
Static files: HTML, CSS, browser JavaScript, assets, Markdown. An app that needs
|
|
1107
|
+
a server at request time — API routes, server-side rendering, a database call —
|
|
1108
|
+
belongs somewhere else, and saying so beats shipping a build that breaks on
|
|
1109
|
+
arrival. Most frameworks have a static export that deploys fine.
|
|
1110
|
+
|
|
1111
|
+
## Deeper reference
|
|
1112
|
+
|
|
1113
|
+
Open these when the task calls for them.
|
|
1114
|
+
|
|
1115
|
+
| File | Read it when |
|
|
1116
|
+
| --- | --- |
|
|
1117
|
+
${REFERENCES.map((r) => `| \`${r.file}\` | ${r.when} |`).join(`
|
|
1118
|
+
`)}`;
|
|
1119
|
+
}
|
|
1120
|
+
function skillEntryFile() {
|
|
1121
|
+
return `---
|
|
1122
|
+
name: ${SKILL_NAME}
|
|
1123
|
+
description: ${yamlScalar(SKILL_DESCRIPTION)}
|
|
1124
|
+
---
|
|
1125
|
+
|
|
1126
|
+
# Deploy with flypod
|
|
1127
|
+
|
|
1128
|
+
${entryBody()}
|
|
1129
|
+
`;
|
|
1130
|
+
}
|
|
1131
|
+
function skillFiles() {
|
|
1132
|
+
const files = { "SKILL.md": skillEntryFile() };
|
|
1133
|
+
for (const ref of REFERENCES)
|
|
1134
|
+
files[ref.file] = ref.body();
|
|
1135
|
+
return files;
|
|
1136
|
+
}
|
|
1137
|
+
function home(env) {
|
|
1138
|
+
return env.HOME ?? homedir2();
|
|
1139
|
+
}
|
|
1140
|
+
var TARGETS = [
|
|
1141
|
+
{
|
|
1142
|
+
id: "claude",
|
|
1143
|
+
label: "Claude Code",
|
|
1144
|
+
detail: ".claude/skills/flypod/ — loaded on demand",
|
|
1145
|
+
projectDir: (root) => join2(root, ".claude", "skills", SKILL_NAME),
|
|
1146
|
+
globalDir: (env) => join2(home(env), ".claude", "skills", SKILL_NAME)
|
|
1147
|
+
},
|
|
1148
|
+
{
|
|
1149
|
+
id: "agents",
|
|
1150
|
+
label: "Agent Skills (shared)",
|
|
1151
|
+
detail: ".agents/skills/flypod/ — Codex, Cursor, Gemini CLI, Copilot",
|
|
1152
|
+
projectDir: (root) => join2(root, ".agents", "skills", SKILL_NAME),
|
|
1153
|
+
globalDir: (env) => join2(home(env), ".agents", "skills", SKILL_NAME)
|
|
1154
|
+
}
|
|
1155
|
+
];
|
|
1156
|
+
var LEGACY_PATHS = [
|
|
1157
|
+
"AGENTS.md",
|
|
1158
|
+
"GEMINI.md",
|
|
1159
|
+
join2(".github", "copilot-instructions.md"),
|
|
1160
|
+
join2(".cursor", "rules", `${SKILL_NAME}.mdc`),
|
|
1161
|
+
join2(".windsurf", "rules", `${SKILL_NAME}.md`),
|
|
1162
|
+
join2(".clinerules", `${SKILL_NAME}.md`),
|
|
1163
|
+
join2(".roo", "rules", `${SKILL_NAME}.md`)
|
|
1164
|
+
];
|
|
1165
|
+
var LEGACY_SHARED = new Set([
|
|
1166
|
+
"AGENTS.md",
|
|
1167
|
+
"GEMINI.md",
|
|
1168
|
+
join2(".github", "copilot-instructions.md")
|
|
1169
|
+
]);
|
|
1170
|
+
var LEGACY_MARK = `<!-- ${SKILL_NAME}:begin -->`;
|
|
1171
|
+
async function exists(path) {
|
|
1172
|
+
try {
|
|
1173
|
+
await stat(path);
|
|
1174
|
+
return true;
|
|
1175
|
+
} catch {
|
|
1176
|
+
return false;
|
|
1177
|
+
}
|
|
1178
|
+
}
|
|
1179
|
+
async function legacyArtifacts(root) {
|
|
1180
|
+
const found = [];
|
|
1181
|
+
for (const rel of LEGACY_PATHS) {
|
|
1182
|
+
const path = join2(root, rel);
|
|
1183
|
+
if (!await exists(path))
|
|
1184
|
+
continue;
|
|
1185
|
+
if (!LEGACY_SHARED.has(rel)) {
|
|
1186
|
+
found.push(rel);
|
|
1187
|
+
continue;
|
|
1188
|
+
}
|
|
1189
|
+
try {
|
|
1190
|
+
if ((await readFile2(path, "utf8")).includes(LEGACY_MARK))
|
|
1191
|
+
found.push(rel);
|
|
1192
|
+
} catch {}
|
|
1193
|
+
}
|
|
1194
|
+
return found;
|
|
1195
|
+
}
|
|
1196
|
+
async function skillInstalledIn(root) {
|
|
1197
|
+
for (const target of TARGETS) {
|
|
1198
|
+
if (await exists(join2(target.projectDir(root), "SKILL.md")))
|
|
1199
|
+
return true;
|
|
1200
|
+
}
|
|
1201
|
+
return (await legacyArtifacts(root)).length > 0;
|
|
1202
|
+
}
|
|
1203
|
+
async function writeTarget(target, dir) {
|
|
1204
|
+
const results = [];
|
|
1205
|
+
for (const [rel, content] of Object.entries(skillFiles())) {
|
|
1206
|
+
const path = join2(dir, rel);
|
|
1207
|
+
const had = await exists(path);
|
|
1208
|
+
if (had && await readFile2(path, "utf8") === content) {
|
|
1209
|
+
results.push({ target, path, status: "unchanged" });
|
|
1210
|
+
continue;
|
|
1211
|
+
}
|
|
1212
|
+
await mkdir2(dirname2(path), { recursive: true });
|
|
1213
|
+
await writeFile2(path, content, "utf8");
|
|
1214
|
+
results.push({ target, path, status: had ? "updated" : "created" });
|
|
1215
|
+
}
|
|
1216
|
+
return results;
|
|
1217
|
+
}
|
|
1218
|
+
async function buildPlan(root, env, global) {
|
|
1219
|
+
return TARGETS.map((target) => ({
|
|
1220
|
+
target,
|
|
1221
|
+
dir: global ? target.globalDir(env) : target.projectDir(root)
|
|
1222
|
+
}));
|
|
1223
|
+
}
|
|
1224
|
+
async function installSkill(args, io) {
|
|
1225
|
+
const env = io.env ?? process.env;
|
|
1226
|
+
const root = args.cwd ?? process.cwd();
|
|
1227
|
+
const global = Boolean(args.global);
|
|
1228
|
+
const plan = await buildPlan(root, env, global);
|
|
1229
|
+
if (args.list) {
|
|
1230
|
+
io.err(global ? "flypod skill targets (global):" : "flypod skill targets (this project):");
|
|
1231
|
+
io.err("");
|
|
1232
|
+
for (const e of plan)
|
|
1233
|
+
io.out(`● ${e.target.id} ${e.target.detail} ${e.dir}`);
|
|
1234
|
+
io.err("");
|
|
1235
|
+
io.err("Run `flypod install skill` to write them.");
|
|
1236
|
+
return 0;
|
|
1237
|
+
}
|
|
1238
|
+
let chosen;
|
|
1239
|
+
if (args.targets && args.targets.length > 0) {
|
|
1240
|
+
const known = new Set(plan.map((e) => e.target.id));
|
|
1241
|
+
const unknown = args.targets.filter((id) => !known.has(id));
|
|
1242
|
+
if (unknown.length > 0) {
|
|
1243
|
+
io.err(`flypod: unknown target(s): ${unknown.join(", ")}`);
|
|
1244
|
+
io.err(`Known targets: ${TARGETS.map((t) => t.id).join(", ")}`);
|
|
1245
|
+
return 2;
|
|
1246
|
+
}
|
|
1247
|
+
chosen = args.targets;
|
|
1248
|
+
} else if (args.picker && !args.all) {
|
|
1249
|
+
const picked = await args.picker(plan);
|
|
1250
|
+
if (picked === null) {
|
|
1251
|
+
io.err("Cancelled. Nothing written.");
|
|
1252
|
+
return 130;
|
|
1253
|
+
}
|
|
1254
|
+
chosen = picked;
|
|
1255
|
+
} else {
|
|
1256
|
+
chosen = plan.map((e) => e.target.id);
|
|
1257
|
+
}
|
|
1258
|
+
const selected = plan.filter((e) => chosen.includes(e.target.id));
|
|
1259
|
+
if (selected.length === 0) {
|
|
1260
|
+
io.err("No targets selected. Nothing written.");
|
|
1261
|
+
return 0;
|
|
1262
|
+
}
|
|
1263
|
+
if (args.dryRun) {
|
|
1264
|
+
io.err("Would write:");
|
|
1265
|
+
for (const e of selected) {
|
|
1266
|
+
for (const rel of Object.keys(skillFiles()))
|
|
1267
|
+
io.out(join2(e.dir, rel));
|
|
1268
|
+
}
|
|
1269
|
+
return 0;
|
|
1270
|
+
}
|
|
1271
|
+
const results = [];
|
|
1272
|
+
for (const e of selected) {
|
|
1273
|
+
try {
|
|
1274
|
+
results.push(...await writeTarget(e.target, e.dir));
|
|
1275
|
+
} catch (error) {
|
|
1276
|
+
io.err(`flypod: failed to write ${e.dir}: ${error.message}`);
|
|
1277
|
+
return 1;
|
|
1278
|
+
}
|
|
1279
|
+
}
|
|
1280
|
+
for (const e of selected) {
|
|
1281
|
+
const mine = results.filter((r) => r.target.id === e.target.id);
|
|
1282
|
+
const changed2 = mine.filter((r) => r.status !== "unchanged").length;
|
|
1283
|
+
io.err(changed2 > 0 ? ` ✓ wrote ${e.dir}/ (${mine.length} files)` : ` · up to date ${e.dir}/`);
|
|
1284
|
+
}
|
|
1285
|
+
for (const r of results)
|
|
1286
|
+
io.out(r.path);
|
|
1287
|
+
const changed = results.filter((r) => r.status !== "unchanged").length;
|
|
1288
|
+
io.err("");
|
|
1289
|
+
io.err(changed > 0 ? `Your agents now know how to deploy with flypod. Try asking one to "deploy this with flypod".` : "Everything was already up to date.");
|
|
1290
|
+
if (!global) {
|
|
1291
|
+
const legacy = await legacyArtifacts(root);
|
|
1292
|
+
if (legacy.length > 0) {
|
|
1293
|
+
io.err("");
|
|
1294
|
+
io.err("These older flypod instruction files are still in the project:");
|
|
1295
|
+
for (const rel of legacy)
|
|
1296
|
+
io.err(` ${rel}`);
|
|
1297
|
+
io.err("They now duplicate the skill, and their content is out of date.");
|
|
1298
|
+
io.err("Removing the flypod parts is safe — the skill above replaces them.");
|
|
1299
|
+
}
|
|
1300
|
+
}
|
|
1301
|
+
return 0;
|
|
1302
|
+
}
|
|
1303
|
+
|
|
1304
|
+
// src/cli/source.ts
|
|
1305
|
+
async function resolveCliSource(env, cwd) {
|
|
1306
|
+
const explicit = env.FLYPOD_SOURCE;
|
|
1307
|
+
if (explicit)
|
|
1308
|
+
return coerceSource(explicit);
|
|
1309
|
+
try {
|
|
1310
|
+
return await skillInstalledIn(cwd) ? "skill" : "cli";
|
|
1311
|
+
} catch {
|
|
1312
|
+
return "cli";
|
|
1313
|
+
}
|
|
1314
|
+
}
|
|
1315
|
+
|
|
711
1316
|
// src/cli/client.ts
|
|
712
1317
|
var DEVICE_CLIENT_ID = "flypod-cli";
|
|
713
1318
|
var DEVICE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
|
|
@@ -716,7 +1321,7 @@ function resolveCredentials(env, session, overrides) {
|
|
|
716
1321
|
const baseUrl = overrides?.baseUrl ?? session?.base_url ?? env.DEPLOY_URL ?? "https://flypod.dev";
|
|
717
1322
|
return { token, baseUrl };
|
|
718
1323
|
}
|
|
719
|
-
function buildClient(token, baseUrl, fetchImpl) {
|
|
1324
|
+
function buildClient(token, baseUrl, fetchImpl, source = "library") {
|
|
720
1325
|
async function request(method, path, init = {}) {
|
|
721
1326
|
const url = new URL(path, baseUrl);
|
|
722
1327
|
if (init.query) {
|
|
@@ -725,7 +1330,7 @@ function buildClient(token, baseUrl, fetchImpl) {
|
|
|
725
1330
|
url.searchParams.set(key, value);
|
|
726
1331
|
}
|
|
727
1332
|
}
|
|
728
|
-
const headers = {};
|
|
1333
|
+
const headers = { [SOURCE_HEADER]: source };
|
|
729
1334
|
if (token)
|
|
730
1335
|
headers.authorization = `Bearer ${token}`;
|
|
731
1336
|
if (init.json !== undefined)
|
|
@@ -738,6 +1343,7 @@ function buildClient(token, baseUrl, fetchImpl) {
|
|
|
738
1343
|
return {
|
|
739
1344
|
baseUrl,
|
|
740
1345
|
token,
|
|
1346
|
+
source,
|
|
741
1347
|
request,
|
|
742
1348
|
deviceCode: () => request("POST", "/api/auth/device/code", { json: { client_id: DEVICE_CLIENT_ID } }),
|
|
743
1349
|
deviceToken: (deviceCode) => request("POST", "/api/auth/device/token", {
|
|
@@ -766,7 +1372,8 @@ async function createClient(opts) {
|
|
|
766
1372
|
const fetchImpl = opts.fetch ?? fetch;
|
|
767
1373
|
const session = await loadSession(env);
|
|
768
1374
|
const { token, baseUrl } = resolveCredentials(env, session, opts.overrides);
|
|
769
|
-
|
|
1375
|
+
const source = await resolveCliSource(env, opts.cwd ?? process.cwd());
|
|
1376
|
+
return buildClient(token, baseUrl, fetchImpl, source);
|
|
770
1377
|
}
|
|
771
1378
|
|
|
772
1379
|
// src/cli.ts
|
|
@@ -784,30 +1391,30 @@ async function resolveDeployDir(opts = {}) {
|
|
|
784
1391
|
return opts.explicit;
|
|
785
1392
|
const cwd = opts.cwd ?? process.cwd();
|
|
786
1393
|
for (const candidate of BUILD_DIR_CANDIDATES) {
|
|
787
|
-
const dir =
|
|
1394
|
+
const dir = join3(cwd, candidate);
|
|
788
1395
|
try {
|
|
789
|
-
if (!(await
|
|
1396
|
+
if (!(await stat2(dir)).isDirectory())
|
|
790
1397
|
continue;
|
|
791
|
-
if ((await
|
|
1398
|
+
if ((await stat2(join3(dir, "index.html"))).isFile())
|
|
792
1399
|
return dir;
|
|
793
1400
|
} catch {}
|
|
794
1401
|
}
|
|
795
1402
|
throw new Error(`No build output folder found. Looked for ${BUILD_DIR_CANDIDATES.join(", ")} ` + `(each must contain an index.html). Pass the folder explicitly, e.g. \`npx flypod ./dist\`.`);
|
|
796
1403
|
}
|
|
797
1404
|
async function collectDist(path) {
|
|
798
|
-
const info = await
|
|
1405
|
+
const info = await stat2(path);
|
|
799
1406
|
if (info.isFile()) {
|
|
800
1407
|
const name = path.split("/").pop() ?? "index.html";
|
|
801
|
-
return { [name]: await
|
|
1408
|
+
return { [name]: await readFile3(path) };
|
|
802
1409
|
}
|
|
803
1410
|
const files = {};
|
|
804
1411
|
async function walk(current) {
|
|
805
1412
|
for (const entry of await readdir(current, { withFileTypes: true })) {
|
|
806
|
-
const full =
|
|
1413
|
+
const full = join3(current, entry.name);
|
|
807
1414
|
if (entry.isDirectory())
|
|
808
1415
|
await walk(full);
|
|
809
1416
|
else
|
|
810
|
-
files[relative(path, full).split("\\").join("/")] = await
|
|
1417
|
+
files[relative(path, full).split("\\").join("/")] = await readFile3(full);
|
|
811
1418
|
}
|
|
812
1419
|
}
|
|
813
1420
|
await walk(path);
|
|
@@ -818,11 +1425,11 @@ async function deploySite(opts) {
|
|
|
818
1425
|
const baseUrl = opts.baseUrl ?? "https://flypod.dev";
|
|
819
1426
|
const zip = zipSync(opts.files);
|
|
820
1427
|
const bridgeFetch = async (input, init) => handle(new Request(typeof input === "string" ? input : input.url, init));
|
|
821
|
-
const client = buildClient(opts.apiKey, baseUrl, bridgeFetch);
|
|
1428
|
+
const client = buildClient(opts.apiKey, baseUrl, bridgeFetch, opts.source ?? "library");
|
|
822
1429
|
const res = await client.createSite(zip);
|
|
823
1430
|
if (!res.ok)
|
|
824
1431
|
throw new Error(`deploy failed: ${res.status}`);
|
|
825
1432
|
return await res.json();
|
|
826
1433
|
}
|
|
827
1434
|
|
|
828
|
-
export { zipSync, projectsFilePath, atomicWriteFile, saveSession, clearSession, resolveCredentials, createClient, BUILD_DIR_CANDIDATES, resolveDeployDir, collectDist, deploySite };
|
|
1435
|
+
export { zipSync, projectsFilePath, atomicWriteFile, saveSession, clearSession, installSkill, resolveCredentials, createClient, BUILD_DIR_CANDIDATES, resolveDeployDir, collectDist, deploySite };
|