flypod 0.1.1 → 0.4.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
@@ -10,7 +10,8 @@ npx flypod ./dist
10
10
  ## How it works
11
11
 
12
12
  - **No auth to deploy** — POST a zip, receive a URL + one-time tokens
13
- - **Ephemeral by default** — anonymous deploys expire in 14 days; there are no accounts in v0.1. User accounts and site claiming (to keep a site alive past expiry) are on the roadmap, not yet shipped
13
+ - **Ephemeral by default** — anonymous deploys expire in 14 days
14
+ - **Optional accounts** — sign in once at [`flypod.dev/account`](https://flypod.dev/account) and every site you've deployed from that browser becomes permanently yours. CLI keys (`fk_...`) drop anonymous expiry too. See [`docs/identity.md`](https://github.com/sdserranog/flypod/blob/main/docs/identity.md)
14
15
  - **Rollback built-in** — every deploy is versioned; roll back with a single call
15
16
  - **Render loop** — optional headless screenshot + console capture on every deploy
16
17
 
@@ -39,12 +40,16 @@ What you see:
39
40
  https://ab12cd34.flypod.dev
40
41
  ────────────────────────────────────────────────────────
41
42
 
42
- manage token <token>
43
- save it — needed to redeploy or roll back
44
-
45
43
  expires in 14 days · ephemeral by default
44
+
45
+ ship a change flypod update (new version of this site)
46
+ roll back flypod rollback
47
+ history flypod versions
46
48
  ```
47
49
 
50
+ `flypod` always creates a **new site**. To ship changes to the *same* site as a
51
+ new version, use `flypod update` (see below) — not `flypod` again.
52
+
48
53
  ### Agent-friendly modes
49
54
 
50
55
  The CLI detects whether stderr is a TTY. When piped (or under an agent), the
@@ -87,6 +92,7 @@ The URL is always printed alone on stdout in pretty and quiet modes, so
87
92
 
88
93
  | Variable | Description |
89
94
  |----------|-------------|
95
+ | `FLYPOD_API_KEY` | Deploy as your account without `flypod login` (agents / CI). A saved session takes precedence |
90
96
  | `DEPLOY_URL` | Override the deploy server (default: `https://flypod.dev`) |
91
97
  | `NO_COLOR` | Disable ANSI colors |
92
98
  | `FORCE_COLOR` | Force colors even when stderr is not a TTY |
@@ -108,6 +114,103 @@ flypod
108
114
 
109
115
  ---
110
116
 
117
+ ## Versions and rollback
118
+
119
+ Every deploy is a **version**, identified by the content hash of its files.
120
+ `flypod` creates a brand-new site; `flypod update` adds a version to a site you
121
+ already made and points the live URL at it. Old versions are kept, so rollback
122
+ is instant. Re-deploying identical content is a no-op (same hash → same
123
+ version).
124
+
125
+ ```sh
126
+ flypod ./dist # deploy v1 → new site, prints the URL
127
+ flypod update # ship changes to that same site → v2 (now live)
128
+ flypod versions # list every version, newest first (live one marked)
129
+ flypod rollback # make the previous version live again
130
+ flypod rollback <id> # roll back to a specific version (full id or a prefix)
131
+ ```
132
+
133
+ **How `update`/`versions`/`rollback` find the site.** On the first deploy,
134
+ flypod records which site a folder maps to under your config dir
135
+ (`projects.json`, next to the session — **never written into your repo**). From
136
+ that folder the commands need no flags. The registry is self-cleaning: entries
137
+ for expired sites are pruned automatically and it is capped at 64 projects.
138
+
139
+ To act on a site from anywhere — or in a stateless agent that kept the
140
+ `site_id` from the deploy output — pass `--site`:
141
+
142
+ ```sh
143
+ flypod update --site <id> ./dist
144
+ flypod versions --site <id>
145
+ flypod rollback --site <id> <version>
146
+ flypod forget [--site <id>] # drop the folder→site memory
147
+ ```
148
+
149
+ **Auth.** Owned sites (after `flypod login`) authorize by your account key.
150
+ Anonymous sites use a per-site manage token, which flypod stashes in the
151
+ registry for you — pass `--token <manage_token>` to use one from a machine that
152
+ doesn't remember it.
153
+
154
+ `--json` is supported on all three for stable, scriptable output.
155
+
156
+ ---
157
+
158
+ ## Teach your coding agents
159
+
160
+ One command writes a small instruction file into your coding agents so they know
161
+ how to deploy with flypod — no config, no copy-paste.
162
+
163
+ ```sh
164
+ npx flypod install skill
165
+ ```
166
+
167
+ Run in a terminal, it shows a checklist of the agents it found. It always writes
168
+ the universal [`AGENTS.md`](https://agents.md) (read by Codex, Cursor, Copilot,
169
+ Gemini, Zed, Jules, and ~20 more) plus a first-class **Claude Code** skill at
170
+ `.claude/skills/flypod/SKILL.md`, and pre-selects any other agents it detects in
171
+ your repo (Cursor, Windsurf, Cline, Roo, …).
172
+
173
+ ```
174
+ flypod · teach your agents to deploy
175
+
176
+ Install the flypod skill into:
177
+
178
+ › ◉ AGENTS.md universal — Codex, Cursor, Copilot, Gemini, Zed, Jules, +more
179
+ ◉ Claude Code .claude/skills/flypod/SKILL.md — loaded on demand
180
+ ◉ Cursor .cursor/rules/flypod.mdc · detected
181
+ ◯ Windsurf .windsurf/rules/flypod.md
182
+
183
+ ↑/↓ move · space toggle · a all · enter confirm · esc cancel
184
+ ```
185
+
186
+ It's idempotent — shared files (`AGENTS.md`, `copilot-instructions.md`, `GEMINI.md`)
187
+ get a fenced `flypod` block that re-runs replace in place, never clobbering your
188
+ own content. Dedicated rule files are flypod-owned and rewritten wholesale.
189
+
190
+ Non-interactive when piped or under an agent (writes the same defaults), so it
191
+ drops cleanly into setup scripts and CI.
192
+
193
+ ```sh
194
+ flypod install skill --all # write files for every supported agent
195
+ flypod install skill --claude # just the Claude Code skill
196
+ flypod install skill --global # install at the user level (~/.claude + ~/.codex; add --all for ~/.gemini)
197
+ flypod install skill --list # show what's detected and where it would go
198
+ flypod install skill --dry-run # print the planned paths, write nothing
199
+ ```
200
+
201
+ | Target | File written |
202
+ |--------|--------------|
203
+ | `--agents` | `AGENTS.md` (universal) |
204
+ | `--claude` | `.claude/skills/flypod/SKILL.md` |
205
+ | `--cursor` | `.cursor/rules/flypod.mdc` |
206
+ | `--copilot` | `.github/copilot-instructions.md` |
207
+ | `--windsurf` | `.windsurf/rules/flypod.md` |
208
+ | `--cline` | `.clinerules/flypod.md` |
209
+ | `--roo` | `.roo/rules/flypod.md` |
210
+ | `--gemini` | `GEMINI.md` |
211
+
212
+ ---
213
+
111
214
  ## Library
112
215
 
113
216
  ```ts
@@ -141,11 +244,12 @@ Returns a `DeployResult`:
141
244
  interface DeployResult {
142
245
  site_id: string;
143
246
  slug: string;
144
- url: string; // live URL
247
+ url: string; // live URL
145
248
  version_id: string;
146
- expires_at: number; // unix ms; anonymous sites expire 14 days out
147
- claim_token: string; // reserved for forward-compat; claiming not live in v0.1
148
- manage_token: string; // one-time; redeploy, rollback, delete
249
+ expires_at: number | null; // unix ms when anonymous, null when owned (authenticated)
250
+ claim_token?: string; // per-site claim token when anonymous; omitted when owned
251
+ manage_token: string; // one-time; redeploy, rollback, delete
252
+ owner_account_id?: string; // present on authenticated deploys (cookie or API key)
149
253
  next_actions: unknown[];
150
254
  }
151
255
  ```
@@ -156,9 +260,12 @@ Reads a local directory into a `Record<string, Uint8Array>` map for `deploySite`
156
260
 
157
261
  ---
158
262
 
159
- ## Managing a site
263
+ ## Managing a site (HTTP)
160
264
 
161
- All management calls use the `manage_token` returned on first deploy.
265
+ The CLI commands above (`update`, `versions`, `rollback`) wrap these endpoints —
266
+ reach for raw HTTP only when scripting against the API directly. All management
267
+ calls authorize with the `manage_token` returned on first deploy (or an account
268
+ API key for owned sites).
162
269
 
163
270
  ```sh
164
271
  # redeploy a new version
@@ -180,6 +287,37 @@ curl -X POST https://flypod.dev/sites/<id>/rollback \
180
287
 
181
288
  ---
182
289
 
290
+ ## Accounts and bulk claim (v0.2)
291
+
292
+ The `manage_token` keeps working exactly as v0.1 — accounts are an
293
+ upgrade path, not a replacement.
294
+
295
+ ```sh
296
+ flypod login --key fk_... # save an API key minted at flypod.dev/account
297
+ flypod list # your sites
298
+ flypod claim <id> <token> # attach an anonymous deploy by its per-site token
299
+ flypod keys create # mint a new API key (for agents / CI)
300
+ flypod logout # forget the local key
301
+ ```
302
+
303
+ After running `flypod login` once, every subsequent `flypod` deploy is
304
+ attributed to your account: no expiry, no claim_token, listed under
305
+ `flypod list`. The same applies in the browser: sign in at
306
+ `flypod.dev/account` and every site you've deployed from that browser
307
+ gets absorbed in one bulk-UPDATE.
308
+
309
+ For agents and CI, set `FLYPOD_API_KEY=fk_…` and the CLI sends it as
310
+ `Authorization: Bearer fk_…` on every request. Same key works in curl, in
311
+ GitHub Actions, in your own code.
312
+
313
+ Login on the web uses **magic link** or **email + password** — pick the one you
314
+ prefer; both land you in the same account. The full design (Better Auth
315
+ `anonymous` + `magicLink` + `apiKey` plugins plus core email/password on
316
+ Cloudflare Workers + Turso, with `onLinkAccount` powering bulk claim) is
317
+ documented at [docs/identity.md](https://github.com/sdserranog/flypod/blob/main/docs/identity.md).
318
+
319
+ ---
320
+
183
321
  ## Self-hosting
184
322
 
185
323
  ```ts
@@ -203,6 +341,9 @@ Environment variables / secrets:
203
341
  | `LIBSQL_URL` | — | Turso/libSQL connection URL |
204
342
  | `LIBSQL_AUTH_TOKEN` | — | Turso auth token |
205
343
  | `SAFE_BROWSING_KEY` | — | Enables Google Safe Browsing link scan |
344
+ | `BETTER_AUTH_SECRET` | — | _v0.2:_ Better Auth signing secret (32+ random bytes) |
345
+ | `RESEND_API_KEY` | — | _v0.2:_ Resend API key for magic-link email delivery |
346
+ | `RESEND_FROM` | `notifications@flypod.dev` | _v0.2:_ verified sender address for magic links |
206
347
 
207
348
  ---
208
349