flypod 0.8.0 → 0.9.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/LICENSE CHANGED
@@ -1,21 +1,48 @@
1
- MIT License
1
+ flypod CLI — Licence
2
+ Copyright (c) 2026 Sergio Serrano. All rights reserved.
2
3
 
3
- Copyright (c) 2026 Sergio Serrano
4
+ This software is proprietary. It is published on npm so that it can be
5
+ installed and run; publication is not a grant of rights beyond those below.
4
6
 
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
7
+ 1. Permission
11
8
 
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
9
+ You may install, copy and run this package, and use it to deploy content to the
10
+ flypod service, for any purpose including commercial use. You may install it as
11
+ a dependency of your own projects and in your CI systems, and cache it in a
12
+ private registry or lockfile for that purpose.
13
+
14
+ 2. Restrictions
15
+
16
+ Except as permitted above, and except where the following cannot lawfully be
17
+ restricted, you may not:
18
+
19
+ a. redistribute, republish or sell this package or a modified copy of it;
20
+ b. modify, adapt or create derivative works from it;
21
+ c. reverse engineer, decompile or disassemble it, other than to the extent
22
+ necessary for interoperability or as permitted by applicable law;
23
+ d. remove or alter this licence or any copyright notice.
24
+
25
+ 3. Service
26
+
27
+ Use of the flypod service through this software is additionally governed by the
28
+ flypod Terms of Service and Privacy Policy at https://flypod.dev/terms and
29
+ https://flypod.dev/privacy. Nothing here grants rights to the flypod service
30
+ itself, its source code, or its trademarks.
31
+
32
+ 4. Third-party components
33
+
34
+ This package includes third-party open-source components, which remain under
35
+ their own licences. Nothing in this licence limits the rights you have under
36
+ those licences.
37
+
38
+ 5. No warranty; no liability
14
39
 
15
40
  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
41
  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
42
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. TO THE MAXIMUM EXTENT
43
+ PERMITTED BY LAW, THE COPYRIGHT HOLDER SHALL NOT BE LIABLE FOR ANY CLAIM,
44
+ DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
45
+ OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR ITS USE.
46
+
47
+ Nothing in this licence excludes or limits liability where that exclusion or
48
+ limitation is not permitted by applicable law.
package/README.md CHANGED
@@ -7,12 +7,8 @@ npx flypod ./dist
7
7
  # → https://ab12cd34.flypod.dev
8
8
  ```
9
9
 
10
- No account. No config file. No project to create. Nothing has to be set up
11
- first — which is why a person, a shell script, a CI job, or a coding agent can
12
- all finish a deploy unattended, in one call.
13
-
14
10
  ```
15
- flypod v0.6.1
11
+ flypod v0.8.0
16
12
 
17
13
  account anonymous · deploy now, flypod login later to keep it
18
14
  source dist 12 files · 1.2 MB
@@ -30,13 +26,28 @@ all finish a deploy unattended, in one call.
30
26
  history flypod versions
31
27
  ```
32
28
 
33
- The URL is always printed alone on **stdout**; everything else goes to stderr.
34
- `URL=$(npx flypod -q)` and `npx flypod | tee url.txt` both work. (The elapsed
35
- time above is one illustrative run, not a benchmark — your line shows whatever
36
- your deploy actually took.)
29
+ That URL is real, public, and HTTPS. Send it to someone. (The elapsed time above
30
+ is one illustrative run, not a benchmark — your line shows whatever your deploy
31
+ actually took.)
32
+
33
+ **Nothing has to be set up first.** No account, no config file, no project to
34
+ create, no framework to detect, no dashboard to learn. Which is the interesting
35
+ part: take the human step out of the deploy path and the deploy path becomes
36
+ automatable. A person, a shell script, a CI job, or a coding agent can all
37
+ finish a deploy unattended, in one call, with nothing provisioned in advance.
37
38
 
38
- **Temporary, then yours.** There are only two states, and one command between
39
- them:
39
+ **And nothing is stuck.** Every deploy is a version, so shipping a change keeps
40
+ the same URL and a bad ship is one command from undone:
41
+
42
+ ```sh
43
+ flypod update # new version, same URL
44
+ flypod versions # every version, newest first
45
+ flypod rollback # the previous one is live again
46
+ ```
47
+
48
+ A deploy made without an account is **temporary** — it expires in 14 days, which
49
+ is right for a preview or a demo. `flypod login` makes it **yours**: no expiry,
50
+ listed under `flypod list`.
40
51
 
41
52
  | State | What it means |
42
53
  |-------|---------------|
@@ -52,37 +63,25 @@ That's the whole ownership model. `flypod login` claims **every** anonymous site
52
63
  this machine remembers, not just the last one — so "deploy now, log in whenever"
53
64
  really is the path. You never have to learn what a token is.
54
65
 
55
- ## Contents
56
-
57
- - [Teach your coding agents to deploy](#teach-your-coding-agents-to-deploy)
58
- - [How do I deploy a folder?](#how-do-i-deploy-a-folder)
59
- - [How do I ship a change to the same site?](#how-do-i-ship-a-change-to-the-same-site)
60
- - [How do I roll back?](#how-do-i-roll-back)
61
- - [How do I use flypod from an agent or CI?](#how-do-i-use-flypod-from-an-agent-or-ci)
62
- - [Flags](#flags)
63
- - [Environment variables](#environment-variables)
64
- - [Exit codes](#exit-codes)
65
- - [How long does a deploy last?](#how-long-does-a-deploy-last)
66
- - [What flypod doesn't do](#what-flypod-doesnt-do)
67
- - [Comments on a deployed site](#comments-on-a-deployed-site)
68
- - [Accounts](#accounts)
69
- - [What does flypod write to disk?](#what-does-flypod-write-to-disk)
70
- - [Library API](#library-api)
71
- - [HTTP API](#http-api)
66
+ Before you start, [flypod.dev/limits](https://flypod.dev/limits) is the honest
67
+ list of what flypod does and does not do — static files only, no server code, no
68
+ build step, 14-day anonymous expiry, and the upload sizes the service ships
69
+ with. It is worth ninety seconds; the short version is
70
+ [below](#what-flypod-doesnt-do).
72
71
 
73
72
  ---
74
73
 
75
74
  ## Teach your coding agents to deploy
76
75
 
77
- One command writes a small instruction file into your coding agents, so they
78
- know how to deploy with flypod without being told each time.
76
+ If you work with a coding agent, this is the command that matters. One run
77
+ writes an [Agent Skill](https://agentskills.io) into your repo, and from then on
78
+ the agent deploys without being told how:
79
79
 
80
80
  ```sh
81
81
  npx flypod install skill
82
82
  ```
83
83
 
84
- Run it once, in a repo. It writes an [Agent Skill](https://agentskills.io) into
85
- the two directories every major agent reads:
84
+ It writes into the two directories every major agent reads:
86
85
 
87
86
  | Directory | Read by |
88
87
  |-----------|---------|
@@ -90,7 +89,32 @@ the two directories every major agent reads:
90
89
  | `.agents/skills/flypod/` | Codex, Cursor, Gemini CLI, GitHub Copilot |
91
90
 
92
91
  Both get the same files, because `SKILL.md` is one open format now rather than a
93
- different dialect per vendor.
92
+ different dialect per vendor. If you manage skills with the `skills` CLI
93
+ instead, the same payload installs from its public packaging repo:
94
+
95
+ ```sh
96
+ npx skills add flypod-dev/flypod-skill
97
+ ```
98
+
99
+ **What the agent learns.** A short `SKILL.md` it always loads: the deploy
100
+ command, how to read `--json` and surface the `url`, how to check `warnings`
101
+ before reporting success, why `flypod update` and not a second `flypod`, the
102
+ temporary → `flypod login` → yours model (and that tokens are secrets an agent
103
+ never needs to save), the `FLYPOD_TOKEN` path for headless runs, and the
104
+ static-only boundary so it doesn't pick flypod for an app with server routes.
105
+
106
+ Alongside it, reference docs the agent opens only when the task needs them — so
107
+ they cost nothing until they're wanted:
108
+
109
+ ```
110
+ .claude/skills/flypod/
111
+ ├── SKILL.md the deploy loop — always loaded
112
+ └── reference/
113
+ ├── updates-and-versions.md update, versions, rollback, --site
114
+ ├── publishing-markdown.md deploying .md as a rendered site
115
+ ├── comments.md review loop on a deployed preview
116
+ └── troubleshooting.md exit codes, warnings, CI, env vars
117
+ ```
94
118
 
95
119
  In a terminal you get a checklist:
96
120
 
@@ -108,28 +132,6 @@ In a terminal you get a checklist:
108
132
  Piped, or run by an agent, it's non-interactive and writes both — so it drops
109
133
  cleanly into a setup script.
110
134
 
111
- **What it contains.** A short `SKILL.md` the agent always loads: the deploy
112
- command, how to read `--json` and surface the `url`, why `flypod update` and not
113
- a second `flypod`, the temporary → `flypod login` → yours model (and that tokens
114
- are secrets an agent never needs to save), the `FLYPOD_TOKEN` path for headless
115
- runs, and the static-only boundary so an agent doesn't pick flypod for an app
116
- with server routes.
117
-
118
- Alongside it, reference docs the agent opens only when the task needs them —
119
- so they cost nothing until they're wanted:
120
-
121
- ```
122
- .claude/skills/flypod/
123
- ├── SKILL.md the deploy loop — always loaded
124
- └── reference/
125
- ├── updates-and-versions.md update, versions, rollback, --site
126
- ├── publishing-markdown.md deploying .md as a rendered site
127
- ├── comments.md review loop on a deployed preview
128
- └── troubleshooting.md exit codes, warnings, CI, env vars
129
- ```
130
-
131
- **Flags:**
132
-
133
135
  ```sh
134
136
  flypod install skill # both directories
135
137
  flypod install skill --claude # just the Claude Code skill
@@ -152,6 +154,24 @@ earlier version, the command points them out and leaves the removal to you.
152
154
 
153
155
  ---
154
156
 
157
+ ## Contents
158
+
159
+ - [How do I deploy a folder?](#how-do-i-deploy-a-folder)
160
+ - [How do I ship a change to the same site?](#how-do-i-ship-a-change-to-the-same-site)
161
+ - [How do I roll back?](#how-do-i-roll-back)
162
+ - [How do I use flypod from an agent or CI?](#how-do-i-use-flypod-from-an-agent-or-ci)
163
+ - [Deploying Markdown](#deploying-markdown)
164
+ - [Flags](#flags)
165
+ - [Environment variables](#environment-variables)
166
+ - [Exit codes](#exit-codes)
167
+ - [How long does a deploy last?](#how-long-does-a-deploy-last)
168
+ - [What flypod doesn't do](#what-flypod-doesnt-do)
169
+ - [Comments on a deployed site](#comments-on-a-deployed-site)
170
+ - [Accounts](#accounts)
171
+ - [What does flypod write to disk?](#what-does-flypod-write-to-disk)
172
+ - [Library API](#library-api)
173
+ - [HTTP API](#http-api)
174
+
155
175
  ## How do I deploy a folder?
156
176
 
157
177
  Point `flypod` at the folder of built files. It zips them, uploads them, and
@@ -170,6 +190,9 @@ With no path, flypod tries these in order and takes the first one that exists
170
190
  dist · build · out · .output/public · .vercel/output/static · public · _site
171
191
  ```
172
192
 
193
+ The URL is always printed alone on **stdout**; everything else goes to stderr.
194
+ `URL=$(npx flypod -q)` and `npx flypod | tee url.txt` both work.
195
+
173
196
  `flypod` always creates a **new site**. To ship changes to a site you already
174
197
  made, use [`flypod update`](#how-do-i-ship-a-change-to-the-same-site) — not
175
198
  `flypod` again.
@@ -259,7 +282,9 @@ flypod rollback # previous version becomes live
259
282
  flypod rollback <id> # a specific version — full id or an unambiguous prefix
260
283
  ```
261
284
 
262
- `versions` prints tab-separated `version_id created_at live` on stdout.
285
+ `versions` prints tab-separated `version_id created_at live` on stdout,
286
+ with `created_at` as a readable UTC date. `--json` keeps it as epoch
287
+ milliseconds, so scripts and agents parse the same value they always did.
263
288
  `--json` is supported on `update`, `versions`, and `rollback` for stable,
264
289
  scriptable output.
265
290
 
@@ -284,10 +309,26 @@ npx flypod ./dist --json
284
309
  "source": "dist",
285
310
  "files": 12,
286
311
  "bytes": 1234567,
287
- "elapsed_ms": 812
312
+ "elapsed_ms": 812,
313
+ "healed": ["spa-fallback"],
314
+ "warnings": []
288
315
  }
289
316
  ```
290
317
 
318
+ **Read `warnings` before you report success.** A deploy can exit 0 and still
319
+ serve a site that's broken for visitors, and this array is the only signal that
320
+ says so. Each entry carries a `code` and a `fix_recipe` naming the change to
321
+ make — `missing-index` when nothing is served at `/`, `not-spa` when the build
322
+ ships scripts alongside visible body content, so client-side routing fallback
323
+ stays off and deep links will 404 on refresh.
324
+
325
+ `healed` is the other half: problems flypod fixed on your behalf. `spa-fallback`
326
+ there means it recognised a single-page app, so unknown paths serve `index.html`
327
+ and client-side routing works with nothing configured.
328
+
329
+ For an agent, that pair is a closed loop — deploy, read the receipt, apply the
330
+ `fix_recipe`, `flypod update` — without a human in it.
331
+
291
332
  `expires_at` is epoch **milliseconds** while the site is temporary, and `null`
292
333
  once it's yours. On an authenticated deploy `owner_account_id` is present and
293
334
  `claim_token` is absent — keys that don't apply are omitted rather than emitted
@@ -313,6 +354,32 @@ token in the environment:
313
354
  FLYPOD_TOKEN=<session-token> npx flypod ./dist --json
314
355
  ```
315
356
 
357
+ ## Deploying Markdown
358
+
359
+ Point flypod at `.md` files and it renders them into a browsable site — no
360
+ static-site generator, no theme, no build step.
361
+
362
+ ```sh
363
+ npx flypod ./report.md # one document
364
+ npx flypod ./notes # a folder of documents
365
+ ```
366
+
367
+ Rendering kicks in when the deploy has **no `index.html` at its root** and at
368
+ least one `.md`, `.markdown`, or `.mdx` file. That condition is deliberate: a
369
+ real static site that happens to ship a stray `README.md` is never hijacked.
370
+
371
+ You get one page per document, navigation across all of them, a title from the
372
+ first `#` heading, light and dark themes applied before first paint, and
373
+ sanitized HTML — inline `<script>`, `on*` attributes, and `javascript:` links
374
+ are stripped.
375
+
376
+ The Markdown sources survive. A browser opening the URL gets the styled page; a
377
+ client that asks for Markdown gets the original back from the same URL:
378
+
379
+ ```sh
380
+ curl -H 'Accept: text/markdown' https://ab12cd34.flypod.dev/guide.html
381
+ ```
382
+
316
383
  ## Flags
317
384
 
318
385
  Deploy flags:
@@ -385,16 +452,20 @@ login` is the path you want.)
385
452
 
386
453
  ## What flypod doesn't do
387
454
 
388
- Stated up front, as design decisions, so nothing is a surprise on day two.
455
+ Stated up front, as design decisions, so nothing is a surprise on day two. The
456
+ long version, with the reasoning attached, is at
457
+ [flypod.dev/limits](https://flypod.dev/limits).
389
458
 
390
459
  - **Static files only.** HTML, CSS, JS, images, Markdown, assets. If a browser
391
460
  can render it, it ships.
392
461
  - **No server code.** No functions, no edge middleware, no request handlers.
393
462
  - **No databases.** Nothing stateful behind the site.
394
- - **No build step.** flypod ships your build *output*; it never runs your
395
- bundler. Point it at `dist/`, not at the project root.
396
- - **No build step, no CI/CD integration.** flypod never runs your bundler and has no opinions about
397
- your git history.
463
+ - **No build step, and no CI/CD integration.** flypod ships your build *output*;
464
+ it never runs your bundler and has no opinions about your git history. Point
465
+ it at `dist/`, not at the project root.
466
+ - **No custom domains.** Every site lives at `<site-id>.flypod.dev`. There is no
467
+ DNS change to make, which is exactly why a script or an agent can produce a
468
+ working URL unattended.
398
469
  - **No dashboard you're expected to live in.** The CLI and the URL are the
399
470
  product.
400
471
  - **Not permanent by default.** Anonymous deploys last 14 days.
@@ -425,6 +496,10 @@ flypod comments reopen <site> <thread_id>
425
496
  Modes: `anonymous` (anyone can comment), `passcode` (a shared passcode gates
426
497
  posting), `approved` (comments appear after review).
427
498
 
499
+ Reviewers need no account in `anonymous` mode, which is the point: ship a
500
+ preview, collect what came back as JSON, fix, `flypod update`, resolve the
501
+ thread.
502
+
428
503
  ## Accounts
429
504
 
430
505
  Accounts are the upgrade, not the entry fee. Everything above works without
@@ -502,6 +577,8 @@ interface DeployResult {
502
577
  claim_token?: string; // anonymous only — attaches the site to an account
503
578
  manage_token: string; // redeploy / rollback / claim
504
579
  owner_account_id?: string; // present on authenticated deploys
580
+ healed?: string[]; // problems the deploy pipeline fixed for you
581
+ warnings?: Array<{ code: string; fix_recipe: string }>;
505
582
  next_actions: unknown[];
506
583
  }
507
584
  ```
@@ -553,6 +630,10 @@ curl -X POST https://flypod.dev/sites/<id>/rollback \
553
630
 
554
631
  ---
555
632
 
556
- Docs: [flypod.dev](https://flypod.dev) · [docs.flypod.dev](https://docs.flypod.dev)
633
+ Docs: [flypod.dev](https://flypod.dev) · [docs.flypod.dev](https://docs.flypod.dev) ·
634
+ [limits](https://flypod.dev/limits) · [report abuse](https://flypod.dev/abuse)
557
635
 
558
- MIT licensed.
636
+ flypod is a hosted service. This package is published so it can be installed and
637
+ run — see [`LICENSE`](./LICENSE) for the terms. The agent-skill files it writes
638
+ are MIT-licensed separately, at
639
+ [flypod-dev/flypod-skill](https://github.com/flypod-dev/flypod-skill).
@@ -11,7 +11,7 @@ import {
11
11
  resolveDeployDir,
12
12
  saveSession,
13
13
  zipSync
14
- } from "../cli-g2wb2hxm.js";
14
+ } from "../cli-db9gcrd0.js";
15
15
 
16
16
  // bin/deploy.ts
17
17
  import { readFile as readFile2 } from "node:fs/promises";
@@ -94,6 +94,110 @@ async function forgetSite(site_id, env) {
94
94
  return removed;
95
95
  }
96
96
 
97
+ // src/cli/receipt.ts
98
+ var DAY_MS = 86400000;
99
+ var ANSI = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g");
100
+ var LABEL = 15;
101
+ var COMMAND = 18;
102
+ function daysUntil(expiresAt, now) {
103
+ return Math.max(0, Math.round((expiresAt - now) / DAY_MS));
104
+ }
105
+ var MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
106
+ function expiryDate(expiresAt) {
107
+ const d = new Date(expiresAt);
108
+ return `${d.getUTCDate()} ${MONTHS[d.getUTCMonth()]} ${d.getUTCFullYear()}`;
109
+ }
110
+ function timestamp(ms) {
111
+ const d = new Date(ms);
112
+ const hh = String(d.getUTCHours()).padStart(2, "0");
113
+ const mm = String(d.getUTCMinutes()).padStart(2, "0");
114
+ return `${expiryDate(ms)} ${hh}:${mm} UTC`;
115
+ }
116
+ var LOOP = [
117
+ { label: "ship a change", command: "flypod update", effect: "new version, same URL" },
118
+ { label: "undo", command: "flypod rollback", effect: "previous version, instantly" },
119
+ { label: "history", command: "flypod versions", effect: "every version, newest first" }
120
+ ];
121
+ var PLAIN = {
122
+ dim: (s) => s,
123
+ bold: (s) => s,
124
+ muted: (s) => s,
125
+ accent: (s) => s,
126
+ ok: (s) => s
127
+ };
128
+ function gutter(label) {
129
+ return label.padEnd(LABEL, " ");
130
+ }
131
+ function row(label, command, effect, s) {
132
+ return ` ${s.muted(gutter(label))}${s.bold(command.padEnd(COMMAND, " "))}${s.dim(effect)}`;
133
+ }
134
+ function wrap(effect, s) {
135
+ return ` ${" ".repeat(LABEL + COMMAND)}${s.dim(effect)}`;
136
+ }
137
+ function note(label, text, s) {
138
+ return ` ${s.muted(gutter(label))}${s.dim(text)}`;
139
+ }
140
+ function expiryLines(opts) {
141
+ if (opts.expiresAt === null)
142
+ return [];
143
+ const s = opts.style ?? PLAIN;
144
+ const days = daysUntil(opts.expiresAt, opts.now ?? Date.now());
145
+ const when = `${expiryDate(opts.expiresAt)} · ${days} day${days === 1 ? "" : "s"}`;
146
+ return [
147
+ opts.check === false ? note("expires", when, s) : ` ${s.muted(gutter("expires"))}${s.dim(`${when} · `)}${s.bold("flypod versions")}`,
148
+ row("keep it", "flypod login", "drops the expiry from this URL", s),
149
+ wrap("and every site on this machine", s)
150
+ ];
151
+ }
152
+ function deployTail(opts) {
153
+ const style = opts.style ?? PLAIN;
154
+ const lines = LOOP.map((step) => row(step.label, step.command, step.effect, style));
155
+ lines.push("");
156
+ if (opts.expiresAt === null) {
157
+ lines.push(note("expires", opts.owned ? "never · attributed to your account" : "never", style));
158
+ return lines;
159
+ }
160
+ lines.push(...expiryLines({ expiresAt: opts.expiresAt, now: opts.now, style }));
161
+ return lines;
162
+ }
163
+ function updateTail(opts) {
164
+ const s = opts.style ?? PLAIN;
165
+ return [
166
+ ` ${s.ok("✓")} ${s.dim(`version ${opts.versionId} is now live`)}`,
167
+ ` ${s.accent(opts.url)}`,
168
+ ...(opts.warnings ?? []).map((w) => ` ! ${w.code} — ${w.fix_recipe}`),
169
+ row("undo", "flypod rollback", "previous version, instantly", s),
170
+ ...expiryLines({ expiresAt: opts.expiresAt, now: opts.now, style: s })
171
+ ];
172
+ }
173
+ function rollbackTail(opts) {
174
+ const s = opts.style ?? PLAIN;
175
+ return [` ${s.ok("✓")} ${s.dim(`rolled back to ${opts.versionId}`)}`, ` ${s.accent(opts.url)}`];
176
+ }
177
+ function relinkNotice(prev, style) {
178
+ const s = style ?? PLAIN;
179
+ return [
180
+ ` ${s.muted(gutter("linked"))}${s.bold("flypod update")}${s.dim(" ships to")}`,
181
+ ` ${s.muted(gutter(""))}${s.accent(prev.url)}`,
182
+ note("", "this run makes a second site instead", s)
183
+ ];
184
+ }
185
+ function agentNext(opts) {
186
+ const now = opts.now ?? Date.now();
187
+ const expiring = opts.expiresAt !== null;
188
+ return {
189
+ expires_in_days: expiring ? daysUntil(opts.expiresAt, now) : null,
190
+ expires_at_iso: expiring ? new Date(opts.expiresAt).toISOString() : null,
191
+ next: {
192
+ update: "flypod update",
193
+ versions: "flypod versions",
194
+ rollback: "flypod rollback",
195
+ ...expiring ? { keep: "flypod login" } : {}
196
+ },
197
+ next_note: expiring ? `This folder is linked to ${opts.siteId}. Run \`flypod update\` to publish changes to this same URL — running \`flypod\` again creates a different site at a different URL. The site stops serving on the date above unless \`flypod login\` claims it, which removes the expiry and changes nothing else.` : `This folder is linked to ${opts.siteId}. Run \`flypod update\` to publish changes to this same URL — running \`flypod\` again creates a different site at a different URL. This site does not expire.`
198
+ };
199
+ }
200
+
97
201
  // src/cli/commands.ts
98
202
  function siteUrlFrom(site_id, baseUrl) {
99
203
  const host = new URL(baseUrl).host;
@@ -304,7 +408,7 @@ async function attachAnonymousSites(apiKey, baseUrl, io, env) {
304
408
  }
305
409
  if (attached.size > 0) {
306
410
  const word = attached.size === 1 ? "site" : "sites";
307
- io.err(` Attached ${attached.size} ${word}.`);
411
+ io.err(` Attached ${attached.size} ${word} — no expiry now, same URLs.`);
308
412
  }
309
413
  if (skipped.length > 0) {
310
414
  io.err(` Skipped ${skipped.length} (already owned or expired).`);
@@ -370,8 +474,13 @@ async function claim(args, io) {
370
474
  if (changed)
371
475
  await saveProjects(projects, env);
372
476
  } catch {}
373
- io.out(JSON.stringify({ ok: true, site_id: body.site_id, owner_account_id: body.owner_account_id }));
374
- io.err(`Claimed. Owned by ${body.owner_account_id}.`);
477
+ io.out(JSON.stringify({
478
+ ok: true,
479
+ site_id: body.site_id,
480
+ owner_account_id: body.owner_account_id,
481
+ expires_at: null
482
+ }));
483
+ io.err(`Claimed ${body.site_id} — the expiry is gone. Same URL, same versions.`);
375
484
  return 0;
376
485
  }
377
486
  var NO_SITE = "No flypod site is linked to this folder. Run 'flypod' here to create one, or pass --site <id>.";
@@ -470,12 +579,20 @@ async function update(args, io) {
470
579
  }
471
580
  const body = await res.json();
472
581
  await touchLink(target, body.version_id, env);
582
+ const expiresAt = target.rec?.expires_at ?? null;
473
583
  if (args.json) {
474
584
  io.out(JSON.stringify({
475
585
  ok: true,
476
586
  site_id: target.site_id,
477
587
  version_id: body.version_id,
478
- url: body.url
588
+ url: body.url,
589
+ healed: body.healed ?? [],
590
+ warnings: body.warnings ?? [],
591
+ ...agentNext({
592
+ siteId: target.site_id,
593
+ expiresAt,
594
+ owned: expiresAt === null
595
+ })
479
596
  }));
480
597
  return 0;
481
598
  }
@@ -483,7 +600,15 @@ async function update(args, io) {
483
600
  io.out(body.url);
484
601
  return 0;
485
602
  }
486
- io.err(`→ version ${body.version_id} is now live`);
603
+ for (const line of updateTail({
604
+ versionId: body.version_id,
605
+ url: body.url,
606
+ expiresAt,
607
+ warnings: body.warnings,
608
+ style: io.style
609
+ })) {
610
+ io.err(line);
611
+ }
487
612
  io.out(body.url);
488
613
  return 0;
489
614
  }
@@ -496,13 +621,23 @@ async function versions(args, io) {
496
621
  if ("error" in site)
497
622
  return site.error;
498
623
  const { live_version_id, versions: vers } = site.data;
624
+ const expiresAt = site.data.expires_at ?? null;
499
625
  if (args.json) {
500
- io.out(JSON.stringify({ ok: true, site_id: target.site_id, live_version_id, versions: vers }));
626
+ io.out(JSON.stringify({
627
+ ok: true,
628
+ site_id: target.site_id,
629
+ live_version_id,
630
+ versions: vers,
631
+ expires_at: expiresAt,
632
+ ...agentNext({ siteId: target.site_id, expiresAt, owned: expiresAt === null })
633
+ }));
501
634
  return 0;
502
635
  }
503
636
  for (const v of [...vers].reverse()) {
504
- io.out(`${v.version_id} ${v.created_at} ${v.version_id === live_version_id ? "live" : ""}`);
637
+ io.out(`${v.version_id} ${timestamp(v.created_at)} ${v.version_id === live_version_id ? "live" : ""}`);
505
638
  }
639
+ for (const line of expiryLines({ expiresAt, style: io.style, check: false }))
640
+ io.err(line);
506
641
  return 0;
507
642
  }
508
643
  async function rollback(args, io) {
@@ -558,7 +693,13 @@ async function rollback(args, io) {
558
693
  }));
559
694
  return 0;
560
695
  }
561
- io.err(`→ rolled back to ${body.live_version_id}`);
696
+ for (const line of rollbackTail({
697
+ versionId: body.live_version_id,
698
+ url,
699
+ style: io.style
700
+ })) {
701
+ io.err(line);
702
+ }
562
703
  io.out(url);
563
704
  return 0;
564
705
  }
@@ -1261,7 +1402,8 @@ async function runSubcommand(name, argv) {
1261
1402
  out: (line) => process.stdout.write(`${line}
1262
1403
  `),
1263
1404
  err: (line) => process.stderr.write(`${line}
1264
- `)
1405
+ `),
1406
+ style: makeStyle(colorsEnabled(process.stderr))
1265
1407
  };
1266
1408
  switch (name) {
1267
1409
  case "update": {
@@ -1412,6 +1554,16 @@ Ownership — two states, one command:
1412
1554
  Logging in claims EVERY temporary site this machine remembers, not just the
1413
1555
  last one — so "deploy now, log in whenever" works. You never need a token.
1414
1556
 
1557
+ 'flypod versions' prints the expiry date any time, so the end date is never
1558
+ a surprise. Claiming changes nothing else: same URL, same versions.
1559
+
1560
+ Attribution:
1561
+ flypod adds a small block of <meta> and JSON-LD to served HTML so crawlers
1562
+ can tell what hosts the page. It renders nothing and runs no script. To turn
1563
+ it off completely, put this anywhere in your page:
1564
+
1565
+ <meta name="flypod" content="none">
1566
+
1415
1567
  flypod login Sign in (opens your browser to confirm) and
1416
1568
  keep every site deployed from this machine.
1417
1569
  flypod login --token <t> Save a session token directly (skip the browser).
@@ -1524,13 +1676,21 @@ async function main() {
1524
1676
  if (useUI) {
1525
1677
  process.stderr.write(`
1526
1678
  ${style.bold(style.accent("flypod"))} ${style.dim(`v${version}`)}
1527
-
1528
1679
  `);
1529
1680
  if (!apiKey) {
1530
- process.stderr.write(` ${style.muted("account")} ${style.dim("anonymous · deploy now, ")}${style.bold("flypod login")}${style.dim(" later to keep it")}
1531
-
1681
+ process.stderr.write(` ${style.muted("account")} ${style.dim("anonymous · deploy now, ")}${style.bold("flypod login")}${style.dim(" later")}
1532
1682
  `);
1533
1683
  }
1684
+ process.stderr.write(`
1685
+ `);
1686
+ }
1687
+ const priorLink = await projectForDir(process.cwd()).catch(() => null);
1688
+ if (priorLink && useUI) {
1689
+ for (const line of relinkNotice(priorLink, style))
1690
+ process.stderr.write(`${line}
1691
+ `);
1692
+ process.stderr.write(`
1693
+ `);
1534
1694
  }
1535
1695
  let dir;
1536
1696
  try {
@@ -1598,7 +1758,7 @@ async function main() {
1598
1758
  process.stderr.write(` ${style.muted("comments")} ${style.dim(`enabled (${mode})`)}
1599
1759
  `);
1600
1760
  } else {
1601
- process.stderr.write(` ${style.muted("comments")} ${style.dim(`failed to enable — run \`flypod comments enable --site ${result.site_id}\``)}
1761
+ process.stderr.write(` ${style.muted("comments")} ${style.dim("failed — run `flypod comments enable`")}
1602
1762
  `);
1603
1763
  }
1604
1764
  }
@@ -1621,6 +1781,12 @@ async function main() {
1621
1781
  elapsed_ms: elapsed,
1622
1782
  healed: result.healed ?? [],
1623
1783
  warnings: result.warnings ?? [],
1784
+ ...agentNext({
1785
+ siteId: result.site_id,
1786
+ expiresAt: result.expires_at,
1787
+ owned
1788
+ }),
1789
+ ...priorLink && priorLink.site_id !== result.site_id ? { replaced_link: { site_id: priorLink.site_id, url: priorLink.url } } : {},
1624
1790
  ...args.comments ? { comments_enabled: commentsEnabled, comments_mode: args.commentsMode } : {}
1625
1791
  }, null, 2)}
1626
1792
  `);
@@ -1635,8 +1801,7 @@ async function main() {
1635
1801
  return;
1636
1802
  }
1637
1803
  const rule = style.dim("─".repeat(56));
1638
- process.stderr.write(`
1639
- ${rule}
1804
+ process.stderr.write(` ${rule}
1640
1805
  `);
1641
1806
  process.stderr.write(` ${style.ok("●")} ${style.bold("Live")}
1642
1807
  `);
@@ -1645,14 +1810,11 @@ async function main() {
1645
1810
  process.stderr.write(` ${rule}
1646
1811
 
1647
1812
  `);
1648
- const expiry = typeof result.expires_at === "number" ? `in ${Math.max(0, Math.round((result.expires_at - Date.now()) / 86400000))} days · \`flypod login\` keeps this and every other site you deployed here` : result.owner_account_id ? "never . attributed to your account" : "never (claimed)";
1649
- process.stderr.write(` ${style.muted("expires")} ${style.dim(expiry)}
1650
-
1813
+ for (const line of deployTail({ expiresAt: result.expires_at, owned, style })) {
1814
+ process.stderr.write(`${line}
1651
1815
  `);
1652
- process.stderr.write(` ${style.muted("ship a change")} ${style.bold("flypod update")} ${style.dim("(new version of this site)")}
1653
- ` + ` ${style.muted("roll back")} ${style.bold("flypod rollback")}
1654
- ` + ` ${style.muted("history")} ${style.bold("flypod versions")}
1655
-
1816
+ }
1817
+ process.stderr.write(`
1656
1818
  `);
1657
1819
  if (!linkSaved && !owned) {
1658
1820
  process.stderr.write(` ${style.err("!")} ${style.bold("Couldn't remember this site")} ${style.dim(`— can't write ${projectsFilePath()}`)}
@@ -647,7 +647,7 @@ function zipSync(data, opts) {
647
647
 
648
648
  // src/deploy-source.ts
649
649
  var SOURCE_HEADER = "x-flypod-source";
650
- var DEPLOY_SOURCES = ["cli", "browser", "library", "skill", "unknown"];
650
+ var DEPLOY_SOURCES = ["cli", "browser", "library", "skill", "ci", "unknown"];
651
651
  function coerceSource(value) {
652
652
  const normalized = (value ?? "").trim().toLowerCase();
653
653
  return DEPLOY_SOURCES.includes(normalized) ? normalized : "unknown";
@@ -1,3 +1,4 @@
1
+ import { type TailStyle } from "./receipt";
1
2
  type FetchLike = typeof fetch;
2
3
  export interface CommandIO {
3
4
  /** Write a line to stdout (the scriptable surface). */
@@ -12,6 +13,13 @@ export interface CommandIO {
12
13
  cwd?: string;
13
14
  /** Open a URL in the default browser. Tests inject a no-op. */
14
15
  openUrl?: (url: string) => Promise<void>;
16
+ /**
17
+ * How to paint the human-facing lines. Injected by the bin entrypoint so
18
+ * `update`/`rollback` accent their URL exactly as a first deploy does;
19
+ * omitted everywhere else, which renders plain text (and keeps the suite
20
+ * asserting on strings rather than on escape sequences).
21
+ */
22
+ style?: TailStyle;
15
23
  }
16
24
  export declare function login(args: {
17
25
  token?: string;
@@ -0,0 +1,155 @@
1
+ export declare const DAY_MS = 86400000;
2
+ /**
3
+ * The column budget every line printed by this module lives inside.
4
+ *
5
+ * Not a style preference. Every launch asset is a terminal recording rendered
6
+ * at a fixed frame size (`docs/growth/assets/README.md`), and a line that wraps
7
+ * mid-word directly under the URL wrecks the hero frame the whole campaign is
8
+ * built on — that README documents two renders where it already happened. 66
9
+ * columns is the width that buys back a 16:9 frame at a legible glyph size.
10
+ *
11
+ * `test/cli-tail-width.test.ts` fails the build when a line outgrows it, which
12
+ * is the point of doing this in code rather than by eye.
13
+ */
14
+ export declare const TAIL_WIDTH = 66;
15
+ /**
16
+ * Rows `deployTail` may occupy. The surrounding deploy screen (banner, account,
17
+ * source, the ✓ line, and the rule/URL block) is twelve more, which puts the
18
+ * whole thing at nineteen — one 16:9 frame, no scroll.
19
+ */
20
+ export declare const TAIL_ROWS = 7;
21
+ /** What the terminal actually shows, with color escapes discounted. */
22
+ export declare function visibleWidth(line: string): number;
23
+ /** Whole days from `now` until `expiresAt`, floored at 0. */
24
+ export declare function daysUntil(expiresAt: number, now: number): number;
25
+ /**
26
+ * A date a human can put in a calendar: `27 Sep 2026`. Deliberately not
27
+ * locale-formatted — the string is also read by agents and copied into issues,
28
+ * and an unambiguous day-month-year beats a locale-correct 09/27 vs 27/09
29
+ * coin flip.
30
+ */
31
+ export declare function expiryDate(expiresAt: number): string;
32
+ /**
33
+ * A version's timestamp, for the `flypod versions` table: `27 Sep 2026 14:03
34
+ * UTC`. Same day-month-year as `expiryDate` plus the clock, because two
35
+ * versions of the same site are usually minutes apart and a date alone cannot
36
+ * tell them apart.
37
+ *
38
+ * Zoned explicitly. A bare `14:03` next to a wall clock showing something else
39
+ * is the kind of small wrongness that makes someone distrust the whole table,
40
+ * and `--json` still carries the raw epoch for anything that needs to compute.
41
+ */
42
+ export declare function timestamp(ms: number): string;
43
+ /**
44
+ * The version loop, in the order it is used. This is the thing campaigns.md
45
+ * says actually earns retention and it is currently something you "discover
46
+ * later" — so it goes directly under the URL, above the ownership story.
47
+ */
48
+ export declare const LOOP: Array<{
49
+ label: string;
50
+ command: string;
51
+ effect: string;
52
+ }>;
53
+ export interface TailStyle {
54
+ dim(s: string): string;
55
+ bold(s: string): string;
56
+ muted(s: string): string;
57
+ accent(s: string): string;
58
+ ok(s: string): string;
59
+ }
60
+ /**
61
+ * The TTL, and the one command that removes it. Shared by the deploy tail,
62
+ * `flypod update` and `flypod versions` so there is exactly one wording and one
63
+ * width budget to keep, rather than three that drift apart (they had: 82, 118
64
+ * and 63 columns for the same sentence).
65
+ *
66
+ * Empty for a site that doesn't expire — an owned site gets no nag anywhere.
67
+ */
68
+ export declare function expiryLines(opts: {
69
+ expiresAt: number | null;
70
+ now?: number;
71
+ style?: TailStyle;
72
+ /**
73
+ * Name `flypod versions` as the way to see this date again. Off inside
74
+ * `flypod versions` itself, which would be telling someone to run the command
75
+ * they are already looking at the output of.
76
+ */
77
+ check?: boolean;
78
+ }): string[];
79
+ export interface TailOptions {
80
+ /** Epoch ms the site expires, or null when it is owned/permanent. */
81
+ expiresAt: number | null;
82
+ /** Set when the deploy was attributed to an account. */
83
+ owned: boolean;
84
+ now?: number;
85
+ style?: TailStyle;
86
+ }
87
+ /**
88
+ * The lines printed under the live URL, in order. Returned as an array so the
89
+ * test suite asserts on content rather than on one giant template string.
90
+ *
91
+ * Ordering is the argument: the second deploy is the north star, so the loop
92
+ * comes first. Ownership is the safety valve (campaigns.md message hierarchy
93
+ * step 4) and comes after it — an upgrade offered at the end, never a gate at
94
+ * the start.
95
+ */
96
+ export declare function deployTail(opts: TailOptions): string[];
97
+ /**
98
+ * What `flypod update` says after the second deploy — the moment someone
99
+ * stopped trying flypod and started using it.
100
+ *
101
+ * Same rows as the deploy tail, minus the one they just ran. `flypod versions`
102
+ * is named on the expiry line rather than given a row of its own: it does
103
+ * double duty there as both the history command and the way to re-check the
104
+ * date, which is a row saved and nothing lost.
105
+ */
106
+ export declare function updateTail(opts: {
107
+ versionId: string;
108
+ url: string;
109
+ expiresAt: number | null;
110
+ /** Whatever survived the deploy, as the server reported it. */
111
+ warnings?: Array<{
112
+ code: string;
113
+ fix_recipe: string;
114
+ }>;
115
+ now?: number;
116
+ style?: TailStyle;
117
+ }): string[];
118
+ /** What `flypod rollback` says. Lean on purpose: this is a recovery action, not
119
+ * a place to sell anything. The URL is accented, as everywhere else. */
120
+ export declare function rollbackTail(opts: {
121
+ versionId: string;
122
+ url: string;
123
+ style?: TailStyle;
124
+ }): string[];
125
+ /**
126
+ * What to say when `flypod` is run in a folder that already deploys somewhere.
127
+ *
128
+ * This is the single most expensive misunderstanding in the product: re-running
129
+ * `flypod` makes a *new* site at a *new* URL and silently repoints the folder,
130
+ * orphaning the old one. Every such run is a fresh anonymous id server-side, so
131
+ * it reads as another one-and-done first-deployer rather than a second deploy
132
+ * by the same person.
133
+ *
134
+ * It is a notice, never a prompt — the deploy proceeds exactly as before.
135
+ */
136
+ export declare function relinkNotice(prev: {
137
+ site_id: string;
138
+ url: string;
139
+ }, style?: TailStyle): string[];
140
+ export interface AgentNextOptions {
141
+ siteId: string;
142
+ expiresAt: number | null;
143
+ owned: boolean;
144
+ now?: number;
145
+ }
146
+ /**
147
+ * The machine-readable half of everything above. Agents do not read stderr, so
148
+ * without this the 43%+ of deploys that come from a library or a skill never
149
+ * learn that `flypod update` exists — they re-run the deploy verb and make a
150
+ * second site, which is precisely the observed failure.
151
+ *
152
+ * Keys are stable and the values are literal commands, not prose: an agent can
153
+ * execute `next.update` verbatim.
154
+ */
155
+ export declare function agentNext(opts: AgentNextOptions): Record<string, unknown>;
package/dist/src/cli.js CHANGED
@@ -3,10 +3,10 @@ import {
3
3
  collectDist,
4
4
  deploySite,
5
5
  resolveDeployDir
6
- } from "../cli-g2wb2hxm.js";
6
+ } from "../cli-db9gcrd0.js";
7
7
  export {
8
- resolveDeployDir,
9
- deploySite,
8
+ BUILD_DIR_CANDIDATES,
10
9
  collectDist,
11
- BUILD_DIR_CANDIDATES
10
+ deploySite,
11
+ resolveDeployDir
12
12
  };
@@ -7,7 +7,15 @@ export declare const SOURCE_HEADER = "x-flypod-source";
7
7
  * it. It is a device id we minted, not PII — no IP, no user agent.
8
8
  */
9
9
  export declare const ANON_ID_HEADER = "x-flypod-anon-id";
10
- export declare const DEPLOY_SOURCES: readonly ["cli", "browser", "library", "skill", "unknown"];
10
+ /**
11
+ * `ci` is ours, and it exists so the growth report can subtract us from our own
12
+ * numbers. Set `FLYPOD_SOURCE=ci` in anything that deploys on our behalf — a
13
+ * workflow, a load test, a demo recording — and the weekly report excludes it
14
+ * from the north star and from C1/C3/C5 instead of counting us as builders.
15
+ * Without this value in the allowlist the header coerces to `unknown` and stays
16
+ * in the denominator, which is the silent version of the same mistake.
17
+ */
18
+ export declare const DEPLOY_SOURCES: readonly ["cli", "browser", "library", "skill", "ci", "unknown"];
11
19
  export type DeploySource = (typeof DEPLOY_SOURCES)[number];
12
20
  /** Validate a client-supplied source header; anything unrecognized is `unknown`. */
13
21
  export declare function coerceSource(value: string | null | undefined): DeploySource;
package/package.json CHANGED
@@ -1,11 +1,11 @@
1
1
  {
2
2
  "name": "flypod",
3
- "version": "0.8.0",
3
+ "version": "0.9.0",
4
4
  "description": "Zero-auth deploy primitive. Turns any folder into a live URL in one command. For AI agents and humans.",
5
5
  "module": "./dist/src/cli.js",
6
6
  "types": "./dist/src/cli.d.ts",
7
7
  "type": "module",
8
- "license": "MIT",
8
+ "license": "SEE LICENSE IN LICENSE",
9
9
  "exports": {
10
10
  ".": {
11
11
  "types": "./dist/src/cli.d.ts",
@@ -50,7 +50,7 @@
50
50
  "devDependencies": {
51
51
  "@flypod/comments": "workspace:*",
52
52
  "@libsql/client": "^0.17.3",
53
- "@types/bun": "latest",
53
+ "@types/bun": "^1.4.1",
54
54
  "better-auth": "1.6.14",
55
55
  "drizzle-orm": "^0.45.2",
56
56
  "hono": "^4.12.34",