flypod 0.16.0 → 0.17.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.
@@ -1,6 +1,6 @@
1
1
  // src/cli.ts
2
- import { readdir, readFile as readFile3, realpath, stat as stat2 } from "node:fs/promises";
3
- import { join as join3, relative, sep } from "node:path";
2
+ import { readdir, readFile as readFile4, realpath, stat as stat2 } from "node:fs/promises";
3
+ import { join as join4, relative, sep } from "node:path";
4
4
 
5
5
  // src/deploy-source.ts
6
6
  var SOURCE_HEADER = "x-flypod-source";
@@ -18,8 +18,10 @@ function coerceSource(value) {
18
18
  return DEPLOY_SOURCES.includes(normalized) ? normalized : "unknown";
19
19
  }
20
20
 
21
- // src/cli/session.ts
22
- import { readFile, unlink } from "node:fs/promises";
21
+ // src/cli/install-id.ts
22
+ import { randomBytes } from "node:crypto";
23
+ import { readFile } from "node:fs/promises";
24
+ import { join as join2 } from "node:path";
23
25
 
24
26
  // src/cli/paths.ts
25
27
  import { mkdir, rename, writeFile } from "node:fs/promises";
@@ -52,11 +54,80 @@ async function atomicWriteFile(path, content) {
52
54
  await rename(tmp, path);
53
55
  }
54
56
 
57
+ // src/cli/install-id.ts
58
+ var ID_RE = /^[A-Za-z0-9_-]{16,64}$/;
59
+ var VERSION_RE = /^\d{1,3}\.\d{1,3}\.\d{1,3}(?:-[0-9A-Za-z.-]{1,20})?$/;
60
+ var INSTALL_HEADER = "x-flypod-install";
61
+ var INSTALL_NEW_HEADER = "x-flypod-install-new";
62
+ var VERSION_HEADER = "x-flypod-version";
63
+ var RELINK_HEADER = "x-flypod-relink";
64
+ function telemetryOptedOut(env) {
65
+ const dnt = env.DO_NOT_TRACK;
66
+ if (dnt !== undefined && !["", "0", "false"].includes(dnt.trim().toLowerCase()))
67
+ return true;
68
+ const own = env.FLYPOD_TELEMETRY;
69
+ return own !== undefined && ["0", "false", "off", "no"].includes(own.trim().toLowerCase());
70
+ }
71
+ function installFilePath(env = process.env) {
72
+ return join2(configDir(env), "install.json");
73
+ }
74
+ var cache = new Map;
75
+ function installId(env = process.env) {
76
+ if (telemetryOptedOut(env))
77
+ return Promise.resolve(null);
78
+ let path;
79
+ try {
80
+ path = installFilePath(env);
81
+ } catch {
82
+ return Promise.resolve(null);
83
+ }
84
+ let pending = cache.get(path);
85
+ if (!pending) {
86
+ pending = loadOrCreate(path);
87
+ cache.set(path, pending);
88
+ }
89
+ return pending;
90
+ }
91
+ async function loadOrCreate(path) {
92
+ try {
93
+ const saved = JSON.parse(await readFile(path, "utf8"));
94
+ if (typeof saved.install_id === "string" && ID_RE.test(saved.install_id)) {
95
+ return { id: saved.install_id, isNew: false };
96
+ }
97
+ } catch {}
98
+ const id = randomBytes(16).toString("base64url");
99
+ try {
100
+ await atomicWriteFile(path, `${JSON.stringify({ install_id: id, created_at: new Date().toISOString() }, null, 2)}
101
+ `);
102
+ } catch {
103
+ return null;
104
+ }
105
+ return { id, isNew: true };
106
+ }
107
+ var version;
108
+ function setCliVersion(v) {
109
+ version = VERSION_RE.test(v) ? v : undefined;
110
+ }
111
+ async function identityHeaders(env) {
112
+ const headers = {};
113
+ if (version)
114
+ headers[VERSION_HEADER] = version;
115
+ const install = await installId(env);
116
+ if (install) {
117
+ headers[INSTALL_HEADER] = install.id;
118
+ if (install.isNew)
119
+ headers[INSTALL_NEW_HEADER] = "1";
120
+ }
121
+ return headers;
122
+ }
123
+ var FIRST_RUN_NOTICE = "flypod counts deploys with a random id. DO_NOT_TRACK=1 stops it.";
124
+
55
125
  // src/cli/session.ts
126
+ import { readFile as readFile2, unlink } from "node:fs/promises";
56
127
  async function loadSession(env) {
57
128
  try {
58
129
  const path = sessionFilePath(env);
59
- const text = await readFile(path, "utf8");
130
+ const text = await readFile2(path, "utf8");
60
131
  const parsed = JSON.parse(text);
61
132
  if (typeof parsed?.session_token === "string" && typeof parsed?.base_url === "string" && typeof parsed?.created_at === "number") {
62
133
  return parsed;
@@ -82,9 +153,391 @@ async function clearSession(env) {
82
153
  }
83
154
 
84
155
  // src/cli/skill.ts
85
- import { mkdir as mkdir2, readFile as readFile2, stat, writeFile as writeFile2 } from "node:fs/promises";
156
+ import { mkdir as mkdir2, readFile as readFile3, stat, writeFile as writeFile2 } from "node:fs/promises";
86
157
  import { homedir as homedir2 } from "node:os";
87
- import { dirname as dirname2, join as join2 } from "node:path";
158
+ import { dirname as dirname2, join as join3 } from "node:path";
159
+
160
+ // src/cli/screen.ts
161
+ var WIDTH = 66;
162
+ var GUTTER = 10;
163
+ var id = (s) => s;
164
+ var PLAIN = {
165
+ dim: id,
166
+ bold: id,
167
+ muted: id,
168
+ accent: id,
169
+ ok: id,
170
+ err: id,
171
+ warn: id
172
+ };
173
+ function wrap(text, width) {
174
+ const lines = [];
175
+ for (const paragraph of text.split(`
176
+ `)) {
177
+ let line = "";
178
+ for (const word of paragraph.split(/\s+/).filter(Boolean)) {
179
+ if (line && line.length + 1 + word.length > width) {
180
+ lines.push(line);
181
+ line = word;
182
+ } else {
183
+ line = line ? `${line} ${word}` : word;
184
+ }
185
+ }
186
+ lines.push(line);
187
+ }
188
+ return lines;
189
+ }
190
+ function headline(text, detail, s) {
191
+ return ` ${s.ok("✓")} ${text}${detail ? s.dim(` · ${detail}`) : ""}`;
192
+ }
193
+ function hero(url, s) {
194
+ return ` ${s.bold(s.accent(url))}`;
195
+ }
196
+ function field(label, value, hint, s) {
197
+ return ` ${s.muted(label.padEnd(GUTTER))}${value}${hint ? ` ${s.dim(hint)}` : ""}`;
198
+ }
199
+ function notice(title, body, s) {
200
+ return [
201
+ ` ${(s.warn ?? id)("!")} ${s.bold(title)}`,
202
+ ...wrap(body, WIDTH - 4).map((line) => ` ${s.dim(line)}`),
203
+ ""
204
+ ];
205
+ }
206
+ function failure(error, fix, s) {
207
+ const [first = "", ...rest] = wrap(error, WIDTH - 4);
208
+ return [
209
+ ` ${(s.err ?? id)("✗")} ${first}`,
210
+ ...rest.map((line) => ` ${line}`),
211
+ ...fix ? wrap(fix, WIDTH - 4).map((line) => ` ${s.dim(line)}`) : []
212
+ ];
213
+ }
214
+ function shortVersion(versionId) {
215
+ return versionId.slice(0, 8);
216
+ }
217
+
218
+ // src/upload-limits.ts
219
+ var HOSTED_UPLOAD_LIMITS = {
220
+ maxFiles: 200,
221
+ maxTotalBytes: 10 * 1024 * 1024,
222
+ maxZipBytes: 12 * 1024 * 1024
223
+ };
224
+ function uploadLimitsFor(baseUrl) {
225
+ try {
226
+ const host = new URL(baseUrl).hostname;
227
+ return host === "flypod.dev" || host.endsWith(".flypod.dev") ? HOSTED_UPLOAD_LIMITS : null;
228
+ } catch {
229
+ return null;
230
+ }
231
+ }
232
+ function storedZipBytes(files) {
233
+ const encoder = new TextEncoder;
234
+ let total = 22;
235
+ for (const [name, bytes] of Object.entries(files)) {
236
+ total += 76 + 2 * encoder.encode(name).byteLength + bytes.byteLength;
237
+ }
238
+ return total;
239
+ }
240
+
241
+ // src/cli/telemetry.ts
242
+ var REPORT_TIMEOUT_MS = 1500;
243
+ var TELEMETRY_PATH = "/telemetry/cli";
244
+ var run = null;
245
+ var pending = new Set;
246
+ function startFailureReports(opts) {
247
+ if (opts.help) {
248
+ run = null;
249
+ return;
250
+ }
251
+ run = {
252
+ verb: opts.verb,
253
+ env: opts.env ?? process.env,
254
+ fetch: opts.fetch ?? fetch,
255
+ cwd: opts.cwd ?? process.cwd(),
256
+ stdoutPiped: !(opts.stdoutIsTTY ?? process.stdout.isTTY)
257
+ };
258
+ }
259
+ function reportFailure(err, args) {
260
+ const current = run;
261
+ if (!current || telemetryOptedOut(current.env))
262
+ return;
263
+ const agent = current.stdoutPiped || Boolean(args.json);
264
+ const sent = send(current, reportBody(err, current.verb, agent)).catch(() => {});
265
+ pending.add(sent);
266
+ sent.finally(() => pending.delete(sent));
267
+ }
268
+ async function flushFailureReports() {
269
+ if (pending.size === 0)
270
+ return;
271
+ let timer;
272
+ await Promise.race([
273
+ Promise.allSettled([...pending]),
274
+ new Promise((resolve) => {
275
+ timer = setTimeout(resolve, REPORT_TIMEOUT_MS + 50);
276
+ })
277
+ ]);
278
+ clearTimeout(timer);
279
+ }
280
+ async function send(r, body) {
281
+ const controller = new AbortController;
282
+ const timer = setTimeout(() => controller.abort(), REPORT_TIMEOUT_MS);
283
+ try {
284
+ const session = await loadSession(r.env).catch(() => null);
285
+ const { baseUrl } = resolveCredentials(r.env, session);
286
+ if (!uploadLimitsFor(baseUrl))
287
+ return;
288
+ const headers = {
289
+ ...await identityHeaders(r.env),
290
+ [SOURCE_HEADER]: await resolveCliSource(r.env, r.cwd),
291
+ "content-type": "application/json"
292
+ };
293
+ const res = await r.fetch(new URL(TELEMETRY_PATH, baseUrl).toString(), {
294
+ method: "POST",
295
+ headers,
296
+ body: JSON.stringify(body),
297
+ signal: controller.signal
298
+ });
299
+ await res.body?.cancel().catch(() => {});
300
+ } finally {
301
+ clearTimeout(timer);
302
+ }
303
+ }
304
+ function runtime() {
305
+ if ("Deno" in globalThis)
306
+ return "deno";
307
+ return process.versions.bun ? "bun" : "node";
308
+ }
309
+ function reportBody(err, verb, agent) {
310
+ const body = {
311
+ code: err.code,
312
+ verb,
313
+ os: process.platform,
314
+ node: (process.versions.node ?? "").split(".")[0],
315
+ runtime: runtime(),
316
+ agent
317
+ };
318
+ if (err.status !== undefined)
319
+ body.status = err.status;
320
+ for (const [key, value] of Object.entries(err.telemetry ?? {})) {
321
+ if (typeof value === "string" || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value)) {
322
+ body[key] = value;
323
+ }
324
+ }
325
+ return body;
326
+ }
327
+
328
+ // src/cli/errors.ts
329
+ var USAGE_CODES = new Set([
330
+ "usage",
331
+ "unknown_command",
332
+ "unknown_flag",
333
+ "interactive_login_required"
334
+ ]);
335
+ var AUTH_CODES = new Set([
336
+ "not_signed_in",
337
+ "unauthorized",
338
+ "token_rejected",
339
+ "no_token",
340
+ "login_denied"
341
+ ]);
342
+ var RETRY_CODES = new Set([
343
+ "rate_limited",
344
+ "server_error",
345
+ "network",
346
+ "authorization_pending",
347
+ "login_timeout"
348
+ ]);
349
+ function exitCodeFor(code) {
350
+ if (USAGE_CODES.has(code))
351
+ return 2;
352
+ if (AUTH_CODES.has(code))
353
+ return 3;
354
+ if (RETRY_CODES.has(code))
355
+ return 4;
356
+ return 1;
357
+ }
358
+ function errorEnvelope(err) {
359
+ return {
360
+ ok: false,
361
+ code: err.code,
362
+ error: err.error,
363
+ ...err.fix ? { fix: err.fix } : {},
364
+ ...err.status !== undefined ? { status: err.status } : {},
365
+ ...err.extra ?? {}
366
+ };
367
+ }
368
+ function emitError(err, args, io, _opts = {}) {
369
+ if (args.json) {
370
+ io.out(JSON.stringify(errorEnvelope(err)));
371
+ } else {
372
+ for (const line of failure(err.error, err.fix, io.style ?? PLAIN))
373
+ io.err(line);
374
+ }
375
+ reportFailure(err, args);
376
+ return exitCodeFor(err.code);
377
+ }
378
+ function fail(code, error, args, io, opts = {}) {
379
+ return emitError({ code, error, fix: opts.fix, status: opts.status, extra: opts.extra }, args, io, { prefix: opts.prefix });
380
+ }
381
+ async function readServerMessage(res) {
382
+ const text = await res.text().catch(() => "");
383
+ if (!text)
384
+ return { message: `HTTP ${res.status}` };
385
+ try {
386
+ const body = JSON.parse(text);
387
+ const message = typeof body.error === "string" ? body.error : typeof body.message === "string" ? body.message : text;
388
+ return {
389
+ message,
390
+ code: typeof body.code === "string" ? body.code : undefined,
391
+ json: true,
392
+ ...typeof body.fix === "string" && body.fix ? { fix: body.fix } : {},
393
+ ...typeof body.limit === "string" ? { limit: body.limit } : {}
394
+ };
395
+ } catch {
396
+ return { message: text.length > 200 ? `${text.slice(0, 200)}…` : text };
397
+ }
398
+ }
399
+ async function classifyResponse(res, ctx) {
400
+ const said = await readServerMessage(res);
401
+ const err = classifyParsed(res, said, ctx);
402
+ if (said.fix)
403
+ err.fix = said.fix;
404
+ if (err.code === "too_large" && said.limit && SIZE_LIMITS.includes(said.limit)) {
405
+ err.telemetry = { ...err.telemetry, limit: said.limit };
406
+ }
407
+ return err;
408
+ }
409
+ var SIZE_LIMITS = ["files", "total_bytes", "zip_bytes"];
410
+ function classifyParsed(res, said, ctx) {
411
+ const { message, code: serverCode, json } = said;
412
+ const status = res.status;
413
+ const site = ctx.siteId ? ` ${ctx.siteId}` : "";
414
+ const base = { status, error: message };
415
+ if (serverCode === "token_rejected") {
416
+ return {
417
+ ...base,
418
+ code: "token_rejected",
419
+ error: "The credential you sent was not accepted, so nothing was deployed.",
420
+ fix: "Run `flypod login` again, or set a valid FLYPOD_TOKEN (unset it to deploy anonymously)."
421
+ };
422
+ }
423
+ if (serverCode === "challenge_required" || /challenge required/i.test(message)) {
424
+ return {
425
+ ...base,
426
+ code: "challenge_required",
427
+ error: "The server wants a human challenge for this deploy.",
428
+ fix: "Run `flypod login` and deploy again: signed-in deploys skip the challenge."
429
+ };
430
+ }
431
+ switch (status) {
432
+ case 401:
433
+ case 403:
434
+ if (!json && message !== `HTTP ${status}`) {
435
+ return {
436
+ ...base,
437
+ code: "network",
438
+ error: `Something between this machine and the server refused the request (HTTP ${status}): ${message}`,
439
+ fix: "Check the proxy or firewall settings (and DEPLOY_URL, if set), then retry."
440
+ };
441
+ }
442
+ if (serverCode === "blocked") {
443
+ return {
444
+ ...base,
445
+ code: "blocked",
446
+ error: `Deploy refused: ${message}`,
447
+ fix: "The content tripped the abuse guard. Remove the flagged files and try again."
448
+ };
449
+ }
450
+ return {
451
+ ...base,
452
+ code: "unauthorized",
453
+ error: `Not authorized for site${site}.`,
454
+ fix: "Run `flypod login`, or pass --token <manage_token> for a site this machine does not remember."
455
+ };
456
+ case 404:
457
+ return ctx.siteScoped ? {
458
+ ...base,
459
+ code: "site_gone",
460
+ error: `Site${site} is gone (expired or deleted).`,
461
+ fix: "Run `flypod` to create a new site."
462
+ } : { ...base, code: "not_found", error: message };
463
+ case 409:
464
+ return {
465
+ ...base,
466
+ code: "already_claimed",
467
+ error: `Site${site} already belongs to another account.`
468
+ };
469
+ case 400:
470
+ return { ...base, code: "invalid_upload", error: `Rejected: ${message}` };
471
+ case 413:
472
+ return {
473
+ ...base,
474
+ code: "too_large",
475
+ error: /^upload too large\.?$/i.test(message) ? "The upload is larger than the server accepts." : `The server refused the upload: ${message.replace(/\.$/, "")}.`,
476
+ fix: "Shrink the build (fewer files, smaller assets) or split it. See flypod.dev/limits."
477
+ };
478
+ case 429:
479
+ return {
480
+ ...base,
481
+ code: "rate_limited",
482
+ error: "Too many requests from this network right now.",
483
+ fix: "Wait a minute and retry the same command.",
484
+ extra: retryAfter(res)
485
+ };
486
+ default:
487
+ if (status >= 500) {
488
+ return {
489
+ ...base,
490
+ code: "server_error",
491
+ error: `${ctx.verb}: the server returned ${status}.`,
492
+ fix: "Retry in a moment; if it keeps failing, check https://flypod.dev/status."
493
+ };
494
+ }
495
+ return { ...base, code: "bad_request", error: `${ctx.verb}: ${message}` };
496
+ }
497
+ }
498
+ function retryAfter(res) {
499
+ const raw = res.headers.get("retry-after");
500
+ const seconds = raw ? Number(raw) : Number.NaN;
501
+ return Number.isFinite(seconds) ? { retry_after_s: seconds } : {};
502
+ }
503
+ function noBuildDir(message) {
504
+ const cut = message.indexOf(". ");
505
+ if (cut === -1)
506
+ return { code: "no_build_dir", error: message };
507
+ return { code: "no_build_dir", error: message.slice(0, cut + 1), fix: message.slice(cut + 2) };
508
+ }
509
+ function networkError(e, baseUrl) {
510
+ const reason = e instanceof Error ? e.message : String(e);
511
+ const host = baseUrl ? ` ${safeHost(baseUrl)}` : "";
512
+ return {
513
+ code: "network",
514
+ error: `Could not reach the flypod server${host}: ${reason}`,
515
+ fix: "Check your connection (and DEPLOY_URL, if set), then retry."
516
+ };
517
+ }
518
+ function safeHost(url) {
519
+ try {
520
+ return new URL(url).host;
521
+ } catch {
522
+ return url;
523
+ }
524
+ }
525
+ var NO_SITE = {
526
+ code: "no_site",
527
+ error: "No flypod site is linked to this folder.",
528
+ fix: "Run `flypod` here to create one, or pass --site <id>."
529
+ };
530
+ var NOT_SIGNED_IN = {
531
+ code: "not_signed_in",
532
+ error: "Not signed in.",
533
+ fix: "Run `flypod login`, or set FLYPOD_TOKEN."
534
+ };
535
+ function unexpectedError(e) {
536
+ const reason = e instanceof Error ? e.message : String(e);
537
+ return { code: "unexpected", error: `unexpected error: ${reason}` };
538
+ }
539
+
540
+ // src/cli/skill.ts
88
541
  var SKILL_NAME = "flypod";
89
542
  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.";
90
543
  function yamlScalar(value) {
@@ -146,6 +599,12 @@ A version id is a hash of the files, so deploying byte-identical content again
146
599
  is a no-op: same hash, same version, no new entry in the history. A redundant
147
600
  \`flypod update\` is free, and needs no guard.
148
601
 
602
+ ## How long versions last
603
+
604
+ The live version stays as long as the site does. Any other version is deleted
605
+ seven days after it was deployed, so \`flypod rollback\` can reach back about a
606
+ week; \`flypod versions\` shows what is still there.
607
+
149
608
  ## Typical loop
150
609
 
151
610
  \`\`\`sh
@@ -264,7 +723,7 @@ flypod comments off --site <site_id> # disable; existing data is preserve
264
723
  | --- | --- |
265
724
  | \`anonymous\` | anyone with the link, no sign-in — best for quick previews |
266
725
  | \`passcode\` | anyone holding the passcode you set with \`--passcode\` |
267
- | \`approved\` | only people you have approved — best for anything semi-public |
726
+ | \`approved\` | anyone with the link, but each comment stays hidden until the owner approves it — best for anything semi-public |
268
727
 
269
728
  Default when you pass \`--comments\` with no mode: \`anonymous\`.
270
729
 
@@ -292,10 +751,13 @@ flypod comments reopen <site_id> <thread_id>
292
751
  ## Authorization
293
752
 
294
753
  Read verbs follow the site's own policy. **Write verbs — \`post\`, \`resolve\`,
295
- \`reopen\`, and the \`enable\`/\`mode\`/\`off\` verbs — need an account session or an
296
- agent token.** Run \`flypod login\`, or set \`FLYPOD_TOKEN\`. A deploy-only key (one
297
- starting \`fk_\`) is rejected up front with exit code 3; it authorizes deploys and
298
- nothing else. \`reference/troubleshooting.md\` has the full exit-code table.
754
+ \`reopen\`, and the \`enable\`/\`mode\`/\`off\` verbs — need an account session**, and
755
+ \`enable\`/\`mode\`/\`off\` only work on a site that account owns. Run \`flypod login\`,
756
+ or set \`FLYPOD_TOKEN\` to a session token. With no credential they fail with
757
+ \`not_signed_in\` (exit 3). A token starting \`fk_\` is a retired API key that flypod
758
+ no longer accepts for anything: \`post\`, \`resolve\` and \`reopen\` refuse it before
759
+ sending (\`unauthorized\`, exit 3), and a deploy that carries one fails with
760
+ \`token_rejected\`. \`reference/troubleshooting.md\` has the full exit-code table.
299
761
 
300
762
  ## The review loop
301
763
 
@@ -320,18 +782,18 @@ var troubleshootingReference = {
320
782
  | \`0\` | success |
321
783
  | \`1\` | runtime error you can act on — no build folder, site gone, upload rejected or blocked |
322
784
  | \`2\` | usage error — unknown flag or bad arguments, or a login that needs a browser |
323
- | \`3\` | auth — not signed in, credential refused (\`token_rejected\`), sign-in denied |
785
+ | \`3\` | auth — not signed in, credential refused (\`unauthorized\`, \`token_rejected\`), no manage token held (\`no_token\`), sign-in denied |
324
786
  | \`4\` | retryable — rate limited, server 5xx, network failure (including a proxy refusing the request), sign-in still pending |
325
787
 
326
788
  The exit code follows the failure's \`code\`, on every verb. With \`--json\`, every
327
789
  failure prints one line on stdout and nothing on stderr:
328
790
 
329
791
  \`\`\`json
330
- {"ok": false, "code": "rate_limited", "error": "…", "fix": "Wait a minute and retry the same command.", "retry_after_s": 30}
792
+ {"ok": false, "code": "rate_limited", "error": "…", "fix": "Wait a minute and retry the same command.", "status": 429, "retry_after_s": 30}
331
793
  \`\`\`
332
794
 
333
795
  Branch on \`code\` (stable), never on \`error\` (prose). \`fix\` is the literal next
334
- step when there is one. Codes you will meet: \`no_build_dir\`, \`no_files\`,
796
+ step when there is one; \`status\` is the HTTP status when a server answered. Codes you will meet: \`no_build_dir\`, \`no_files\`,
335
797
  \`no_site\`, \`not_signed_in\`, \`unauthorized\`, \`token_rejected\`, \`site_gone\`,
336
798
  \`invalid_upload\`, \`too_large\`, \`blocked\`, \`challenge_required\`,
337
799
  \`rate_limited\`, \`server_error\`, \`network\`, \`unknown_flag\`, \`usage\`.
@@ -341,6 +803,8 @@ step when there is one. Codes you will meet: \`no_build_dir\`, \`no_files\`,
341
803
  names the closest real flag when there is one. \`no_build_dir\` also covers a
342
804
  path that does not exist. \`too_large\` is checked before uploading to flypod.dev
343
805
  (at most 200 files, 10 MB of files, 12 MB as an upload) and names the largest files.
806
+ Read its \`fix\`: when the folder is a project root, or most of it is source maps
807
+ or video, it says so and names the folder or the \`.flypodignore\` line to use.
344
808
 
345
809
  Rarer ones: \`unknown_command\` (a verb that does not exist — \`flypod verisons\`
346
810
  fails this way with \`"fix": "flypod versions"\` instead of deploying a folder
@@ -401,6 +865,11 @@ it would otherwise outlive.
401
865
  | \`FLYPOD_TOKEN\` | Deploy as your account without logging in (agents / CI) |
402
866
  | \`DEPLOY_URL\` | Point at a different flypod server (default \`https://flypod.dev\`) |
403
867
  | \`FLYPOD_CONFIG_DIR\` | Relocate the session + folder→site memory |
868
+ | \`DO_NOT_TRACK\` | \`1\` turns off the CLI's random install id and its failure reports (codes and counts, never file names) |
869
+
870
+ \`FLYPOD_TOKEN\` wins over a saved \`flypod login\` session; \`--token\` and a site's own
871
+ stored manage token win over both. \`FLYPOD_API_KEY\` is read only as a last-resort
872
+ fallback for older setups.
404
873
 
405
874
  ## Getting the full command surface
406
875
 
@@ -515,7 +984,7 @@ When the user wants to sign in and you have no browser, do not run a bare
515
984
 
516
985
  \`\`\`sh
517
986
  flypod login --json
518
- # {"ok":false,"code":"interactive_login_required","verification_uri_complete":"https://…","user_code":"ABCD-1234","device_code":"…","fix":"…"}
987
+ # {"ok":false,"code":"interactive_login_required","error":"…","fix":"…","verification_uri":"https://…","verification_uri_complete":"https://…","user_code":"ABCD-1234","device_code":"…","expires_in":600,"interval":5}
519
988
  \`\`\`
520
989
 
521
990
  It exits at once (code 2). Give the user the URL and the code; when they say
@@ -555,8 +1024,8 @@ choosing between iterations. It is off by default because it makes replaced
555
1024
  versions public: do not turn it on for a site where an earlier version held
556
1025
  something that was removed on purpose. With it on, \`--json\` carries a
557
1026
  \`history_url\` to give the user (two versions side by side), and
558
- \`flypod versions --json\` a \`url\` for each version. Versions that are not live are kept
559
- for seven days.
1027
+ \`flypod versions --json\` a \`url\` for each version. A version that is not live is
1028
+ deleted seven days after it was deployed, so the timeline shows about a week.
560
1029
 
561
1030
  ## Where sites live
562
1031
 
@@ -621,30 +1090,30 @@ var TARGETS = [
621
1090
  id: "claude",
622
1091
  label: "Claude Code",
623
1092
  detail: ".claude/skills/flypod/ — loaded on demand",
624
- projectDir: (root) => join2(root, ".claude", "skills", SKILL_NAME),
625
- globalDir: (env) => join2(home(env), ".claude", "skills", SKILL_NAME)
1093
+ projectDir: (root) => join3(root, ".claude", "skills", SKILL_NAME),
1094
+ globalDir: (env) => join3(home(env), ".claude", "skills", SKILL_NAME)
626
1095
  },
627
1096
  {
628
1097
  id: "agents",
629
1098
  label: "Agent Skills (shared)",
630
1099
  detail: ".agents/skills/flypod/ — Codex, Cursor, Gemini CLI, Copilot",
631
- projectDir: (root) => join2(root, ".agents", "skills", SKILL_NAME),
632
- globalDir: (env) => join2(home(env), ".agents", "skills", SKILL_NAME)
1100
+ projectDir: (root) => join3(root, ".agents", "skills", SKILL_NAME),
1101
+ globalDir: (env) => join3(home(env), ".agents", "skills", SKILL_NAME)
633
1102
  }
634
1103
  ];
635
1104
  var LEGACY_PATHS = [
636
1105
  "AGENTS.md",
637
1106
  "GEMINI.md",
638
- join2(".github", "copilot-instructions.md"),
639
- join2(".cursor", "rules", `${SKILL_NAME}.mdc`),
640
- join2(".windsurf", "rules", `${SKILL_NAME}.md`),
641
- join2(".clinerules", `${SKILL_NAME}.md`),
642
- join2(".roo", "rules", `${SKILL_NAME}.md`)
1107
+ join3(".github", "copilot-instructions.md"),
1108
+ join3(".cursor", "rules", `${SKILL_NAME}.mdc`),
1109
+ join3(".windsurf", "rules", `${SKILL_NAME}.md`),
1110
+ join3(".clinerules", `${SKILL_NAME}.md`),
1111
+ join3(".roo", "rules", `${SKILL_NAME}.md`)
643
1112
  ];
644
1113
  var LEGACY_SHARED = new Set([
645
1114
  "AGENTS.md",
646
1115
  "GEMINI.md",
647
- join2(".github", "copilot-instructions.md")
1116
+ join3(".github", "copilot-instructions.md")
648
1117
  ]);
649
1118
  var LEGACY_MARK = `<!-- ${SKILL_NAME}:begin -->`;
650
1119
  async function exists(path) {
@@ -658,7 +1127,7 @@ async function exists(path) {
658
1127
  async function legacyArtifacts(root) {
659
1128
  const found = [];
660
1129
  for (const rel of LEGACY_PATHS) {
661
- const path = join2(root, rel);
1130
+ const path = join3(root, rel);
662
1131
  if (!await exists(path))
663
1132
  continue;
664
1133
  if (!LEGACY_SHARED.has(rel)) {
@@ -666,7 +1135,7 @@ async function legacyArtifacts(root) {
666
1135
  continue;
667
1136
  }
668
1137
  try {
669
- if ((await readFile2(path, "utf8")).includes(LEGACY_MARK))
1138
+ if ((await readFile3(path, "utf8")).includes(LEGACY_MARK))
670
1139
  found.push(rel);
671
1140
  } catch {}
672
1141
  }
@@ -674,7 +1143,7 @@ async function legacyArtifacts(root) {
674
1143
  }
675
1144
  async function skillInstalledIn(root) {
676
1145
  for (const target of TARGETS) {
677
- if (await exists(join2(target.projectDir(root), "SKILL.md")))
1146
+ if (await exists(join3(target.projectDir(root), "SKILL.md")))
678
1147
  return true;
679
1148
  }
680
1149
  return (await legacyArtifacts(root)).length > 0;
@@ -682,9 +1151,9 @@ async function skillInstalledIn(root) {
682
1151
  async function writeTarget(target, dir) {
683
1152
  const results = [];
684
1153
  for (const [rel, content] of Object.entries(skillFiles())) {
685
- const path = join2(dir, rel);
1154
+ const path = join3(dir, rel);
686
1155
  const had = await exists(path);
687
- if (had && await readFile2(path, "utf8") === content) {
1156
+ if (had && await readFile3(path, "utf8") === content) {
688
1157
  results.push({ target, path, status: "unchanged" });
689
1158
  continue;
690
1159
  }
@@ -700,12 +1169,23 @@ async function buildPlan(root, env, global) {
700
1169
  dir: global ? target.globalDir(env) : target.projectDir(root)
701
1170
  }));
702
1171
  }
703
- async function installSkill(args, io) {
1172
+ async function installSkill(args, callerIo) {
1173
+ const json = Boolean(args.json);
1174
+ const io = json ? { ...callerIo, err: () => {}, out: () => {} } : callerIo;
1175
+ const emit = (value) => callerIo.out(JSON.stringify(value));
704
1176
  const env = io.env ?? process.env;
705
1177
  const root = args.cwd ?? process.cwd();
706
1178
  const global = Boolean(args.global);
707
1179
  const plan = await buildPlan(root, env, global);
708
1180
  if (args.list) {
1181
+ if (json) {
1182
+ emit({
1183
+ ok: true,
1184
+ global,
1185
+ targets: plan.map((e) => ({ id: e.target.id, detail: e.target.detail, dir: e.dir }))
1186
+ });
1187
+ return 0;
1188
+ }
709
1189
  io.err(global ? "flypod skill targets (global):" : "flypod skill targets (this project):");
710
1190
  io.err("");
711
1191
  for (const e of plan)
@@ -717,14 +1197,14 @@ async function installSkill(args, io) {
717
1197
  let chosen;
718
1198
  if (args.targets && args.targets.length > 0) {
719
1199
  const known = new Set(plan.map((e) => e.target.id));
720
- const unknown = args.targets.filter((id) => !known.has(id));
1200
+ const unknown = args.targets.filter((id2) => !known.has(id2));
721
1201
  if (unknown.length > 0) {
722
- io.err(`flypod: unknown target(s): ${unknown.join(", ")}`);
723
- io.err(`Known targets: ${TARGETS.map((t) => t.id).join(", ")}`);
724
- return 2;
1202
+ return fail("usage", `flypod install skill: unknown target(s): ${unknown.join(", ")}`, { json }, callerIo, {
1203
+ fix: `Known targets: ${TARGETS.map((t) => t.id).join(", ")}.`
1204
+ });
725
1205
  }
726
1206
  chosen = args.targets;
727
- } else if (args.picker && !args.all) {
1207
+ } else if (args.picker && !args.all && !json) {
728
1208
  const picked = await args.picker(plan);
729
1209
  if (picked === null) {
730
1210
  io.err("Cancelled. Nothing written.");
@@ -736,14 +1216,24 @@ async function installSkill(args, io) {
736
1216
  }
737
1217
  const selected = plan.filter((e) => chosen.includes(e.target.id));
738
1218
  if (selected.length === 0) {
1219
+ if (json)
1220
+ emit({ ok: true, targets: [], files: [] });
739
1221
  io.err("No targets selected. Nothing written.");
740
1222
  return 0;
741
1223
  }
742
1224
  if (args.dryRun) {
1225
+ if (json) {
1226
+ emit({
1227
+ ok: true,
1228
+ dry_run: true,
1229
+ files: selected.flatMap((e) => Object.keys(skillFiles()).map((rel) => join3(e.dir, rel)))
1230
+ });
1231
+ return 0;
1232
+ }
743
1233
  io.err("Would write:");
744
1234
  for (const e of selected) {
745
1235
  for (const rel of Object.keys(skillFiles()))
746
- io.out(join2(e.dir, rel));
1236
+ io.out(join3(e.dir, rel));
747
1237
  }
748
1238
  return 0;
749
1239
  }
@@ -752,8 +1242,7 @@ async function installSkill(args, io) {
752
1242
  try {
753
1243
  results.push(...await writeTarget(e.target, e.dir));
754
1244
  } catch (error) {
755
- io.err(`flypod: failed to write ${e.dir}: ${error.message}`);
756
- return 1;
1245
+ return fail("unexpected", `Failed to write ${e.dir}: ${error.message}`, { json }, callerIo);
757
1246
  }
758
1247
  }
759
1248
  for (const e of selected) {
@@ -766,16 +1255,27 @@ async function installSkill(args, io) {
766
1255
  const changed = results.filter((r) => r.status !== "unchanged").length;
767
1256
  io.err("");
768
1257
  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.");
769
- if (!global) {
770
- const legacy = await legacyArtifacts(root);
771
- if (legacy.length > 0) {
772
- io.err("");
773
- io.err("These older flypod instruction files are still in the project:");
774
- for (const rel of legacy)
775
- io.err(` ${rel}`);
776
- io.err("They now duplicate the skill, and their content is out of date.");
777
- io.err("Removing the flypod parts is safe — the skill above replaces them.");
778
- }
1258
+ const legacy = global ? [] : await legacyArtifacts(root);
1259
+ if (json) {
1260
+ emit({
1261
+ ok: true,
1262
+ targets: selected.map((e) => ({
1263
+ id: e.target.id,
1264
+ dir: e.dir,
1265
+ changed: results.some((r) => r.target.id === e.target.id && r.status !== "unchanged")
1266
+ })),
1267
+ files: results.map((r) => ({ path: r.path, status: r.status })),
1268
+ legacy
1269
+ });
1270
+ return 0;
1271
+ }
1272
+ if (legacy.length > 0) {
1273
+ io.err("");
1274
+ io.err("These older flypod instruction files are still in the project:");
1275
+ for (const rel of legacy)
1276
+ io.err(` ${rel}`);
1277
+ io.err("They now duplicate the skill, and their content is out of date.");
1278
+ io.err("Removing the flypod parts is safe — the skill above replaces them.");
779
1279
  }
780
1280
  return 0;
781
1281
  }
@@ -800,7 +1300,7 @@ function resolveCredentials(env, session, overrides) {
800
1300
  const baseUrl = overrides?.baseUrl ?? session?.base_url ?? env.DEPLOY_URL ?? "https://flypod.dev";
801
1301
  return { token, baseUrl };
802
1302
  }
803
- function buildClient(token, baseUrl, fetchImpl, source = "library") {
1303
+ function buildClient(token, baseUrl, fetchImpl, source = "library", extraHeaders = {}) {
804
1304
  async function request(method, path, init = {}) {
805
1305
  const url = new URL(path, baseUrl);
806
1306
  if (init.query) {
@@ -809,7 +1309,11 @@ function buildClient(token, baseUrl, fetchImpl, source = "library") {
809
1309
  url.searchParams.set(key, value);
810
1310
  }
811
1311
  }
812
- const headers = { [SOURCE_HEADER]: source };
1312
+ const headers = {
1313
+ ...extraHeaders,
1314
+ ...init.headers,
1315
+ [SOURCE_HEADER]: source
1316
+ };
813
1317
  if (token)
814
1318
  headers.authorization = `Bearer ${token}`;
815
1319
  if (init.json !== undefined)
@@ -836,7 +1340,7 @@ function buildClient(token, baseUrl, fetchImpl, source = "library") {
836
1340
  claimSite: (siteId, claimToken) => request("POST", `/sites/${siteId}/claim`, { json: { claim_token: claimToken } }),
837
1341
  bulkAttach: (sites) => request("POST", "/account/bulk-attach", { json: { sites } }),
838
1342
  getSite: (siteId) => request("GET", `/sites/${siteId}`),
839
- createSite: (zip) => request("POST", "/sites", { zip }),
1343
+ createSite: (zip, opts) => request("POST", "/sites", { zip, headers: opts?.relink ? { [RELINK_HEADER]: "1" } : {} }),
840
1344
  redeploy: (siteId, zip) => request("POST", `/sites/${siteId}/deploys`, { zip }),
841
1345
  rollback: (siteId, versionId) => request("POST", `/sites/${siteId}/rollback`, { json: { version_id: versionId } }),
842
1346
  setTimeline: (siteId, enabled) => request("POST", `/sites/${siteId}/timeline`, { json: { enabled } }),
@@ -853,7 +1357,8 @@ async function createClient(opts) {
853
1357
  const session = await loadSession(env);
854
1358
  const { token, baseUrl } = resolveCredentials(env, session, opts.overrides);
855
1359
  const source = await resolveCliSource(env, opts.cwd ?? process.cwd());
856
- return buildClient(token, baseUrl, fetchImpl, source);
1360
+ const identity = await identityHeaders(env).catch(() => ({}));
1361
+ return buildClient(token, baseUrl, fetchImpl, source, identity);
857
1362
  }
858
1363
 
859
1364
  // ../../node_modules/.bun/fflate@0.8.3/node_modules/fflate/esm/index.mjs
@@ -1519,11 +2024,11 @@ async function resolveDeployDir(opts = {}) {
1519
2024
  return opts.explicit;
1520
2025
  const cwd = opts.cwd ?? process.cwd();
1521
2026
  for (const candidate of BUILD_DIR_CANDIDATES) {
1522
- const dir = join3(cwd, candidate);
2027
+ const dir = join4(cwd, candidate);
1523
2028
  try {
1524
2029
  if (!(await stat2(dir)).isDirectory())
1525
2030
  continue;
1526
- if ((await stat2(join3(dir, "index.html"))).isFile())
2031
+ if ((await stat2(join4(dir, "index.html"))).isFile())
1527
2032
  return dir;
1528
2033
  } catch {}
1529
2034
  }
@@ -1590,11 +2095,11 @@ async function collectFiles(path) {
1590
2095
  const info = await stat2(path);
1591
2096
  if (info.isFile()) {
1592
2097
  const name = path.split("/").pop() ?? "index.html";
1593
- return { files: { [name]: await readFile3(path) }, skipped: [] };
2098
+ return { files: { [name]: await readFile4(path) }, skipped: [] };
1594
2099
  }
1595
2100
  const rules = DEFAULT_IGNORES.map((p) => compileRule(p, "default"));
1596
2101
  try {
1597
- const text = await readFile3(join3(path, IGNORE_FILE), "utf8");
2102
+ const text = await readFile4(join4(path, IGNORE_FILE), "utf8");
1598
2103
  for (const line of text.split(/\r?\n/)) {
1599
2104
  const rule = compileRule(line, "flypodignore");
1600
2105
  if (rule)
@@ -1607,7 +2112,7 @@ async function collectFiles(path) {
1607
2112
  const active = new Set([root]);
1608
2113
  async function walk(current, currentReal) {
1609
2114
  for (const entry of await readdir(current, { withFileTypes: true })) {
1610
- const full = join3(current, entry.name);
2115
+ const full = join4(current, entry.name);
1611
2116
  const rel = relative(path, full).split("\\").join("/");
1612
2117
  if (rel === IGNORE_FILE)
1613
2118
  continue;
@@ -1628,7 +2133,7 @@ async function collectFiles(path) {
1628
2133
  continue;
1629
2134
  }
1630
2135
  if (isDir) {
1631
- const childReal = real ?? join3(currentReal, entry.name);
2136
+ const childReal = real ?? join4(currentReal, entry.name);
1632
2137
  if (real !== undefined) {
1633
2138
  const inside = real === root || real.startsWith(`${root}${sep}`);
1634
2139
  if (!inside) {
@@ -1644,7 +2149,7 @@ async function collectFiles(path) {
1644
2149
  await walk(full, childReal);
1645
2150
  active.delete(childReal);
1646
2151
  } else {
1647
- files[rel] = await readFile3(full);
2152
+ files[rel] = await readFile4(full);
1648
2153
  }
1649
2154
  }
1650
2155
  }
@@ -1699,4 +2204,4 @@ class DeployError extends Error {
1699
2204
  }
1700
2205
  }
1701
2206
 
1702
- export { projectsFilePath, atomicWriteFile, saveSession, clearSession, installSkill, resolveCredentials, createClient, packDeploy, BUILD_DIR_CANDIDATES, resolveDeployDir, DEFAULT_IGNORES, IGNORE_FILE, collectFiles, collectDist, deploySite, DeployError };
2207
+ export { projectsFilePath, atomicWriteFile, installId, setCliVersion, FIRST_RUN_NOTICE, saveSession, clearSession, PLAIN, headline, hero, field, notice, failure, shortVersion, HOSTED_UPLOAD_LIMITS, uploadLimitsFor, storedZipBytes, startFailureReports, reportFailure, flushFailureReports, exitCodeFor, errorEnvelope, emitError, fail, classifyResponse, noBuildDir, networkError, NO_SITE, NOT_SIGNED_IN, unexpectedError, installSkill, resolveCredentials, createClient, packDeploy, BUILD_DIR_CANDIDATES, resolveDeployDir, DEFAULT_IGNORES, IGNORE_FILE, collectFiles, collectDist, deploySite, DeployError };