flypod 0.10.1 → 0.11.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.
@@ -4,7 +4,15 @@ import { join as join3, relative } from "node:path";
4
4
 
5
5
  // src/deploy-source.ts
6
6
  var SOURCE_HEADER = "x-flypod-source";
7
- var DEPLOY_SOURCES = ["cli", "browser", "library", "skill", "ci", "unknown"];
7
+ var DEPLOY_SOURCES = [
8
+ "cli",
9
+ "browser",
10
+ "library",
11
+ "skill",
12
+ "mcp",
13
+ "ci",
14
+ "unknown"
15
+ ];
8
16
  function coerceSource(value) {
9
17
  const normalized = (value ?? "").trim().toLowerCase();
10
18
  return DEPLOY_SOURCES.includes(normalized) ? normalized : "unknown";
@@ -424,11 +432,10 @@ is the normal path rather than a fallback. To install once: \`npm install -g fly
424
432
  "site_id": "a3f1c2d4e5b60789",
425
433
  "version_id": "…",
426
434
  "expires_at": 1782929906088,
427
- "files": 12,
428
- "bytes": 1234567,
429
- "elapsed_ms": 812,
430
435
  "healed": ["spa-fallback"],
431
- "warnings": []
436
+ "warnings": [],
437
+ "link_saved": true,
438
+ "next": { "update": "flypod update", "versions": "flypod versions", "rollback": "flypod rollback", "keep": "flypod login" }
432
439
  }
433
440
  \`\`\`
434
441
 
@@ -442,10 +449,17 @@ is the normal path rather than a fallback. To install once: \`npm install -g fly
442
449
  - \`site_id\` — names the site for \`--site <id>\` from any other folder.
443
450
  - \`expires_at\` — epoch **milliseconds** while the site is temporary, \`null\` once
444
451
  it belongs to an account.
445
- - \`manage_token\` / \`claim_token\` — secrets, on a first temporary deploy. The CLI
446
- has already saved what it needs, keyed by the folder you deployed from, so
447
- these want no action from you. Keep them out of chat, commits, logs, and PR
448
- descriptions.
452
+ - \`next\` — the literal commands for what comes after. \`next.update\` is how a
453
+ change is shipped to this same URL.
454
+ - \`link_saved\` — whether \`flypod update\` works from this folder with no flags.
455
+ When it is \`false\` (a read-only config dir, typical of CI), the \`next\`
456
+ commands carry \`--site <id>\` and the receipt also has a \`manage_token\`:
457
+ that is the only copy, so pass it as \`--token\` on later commands and keep it
458
+ out of chat, commits, logs, and PR descriptions.
459
+
460
+ The receipt carries no credentials otherwise; the CLI has saved what it needs,
461
+ keyed by the folder you deployed from. \`--json --verbose\` adds tokens, file
462
+ and byte counts, and timing, for the rare job that needs them.
449
463
 
450
464
  \`-q\` prints the URL alone, for a shell variable: \`URL=$(npx flypod ./dist -q)\`.
451
465
 
@@ -518,6 +532,14 @@ a server at request time — API routes, server-side rendering, a database call
518
532
  belongs somewhere else, and saying so beats shipping a build that breaks on
519
533
  arrival. Most frameworks have a static export that deploys fine.
520
534
 
535
+ Paths resolve the way a static export expects: \`/about\` serves
536
+ \`about.html\`, \`/blog/\` serves \`blog/index.html\`, \`/blog\` redirects there,
537
+ and a \`404.html\` in the folder is used for missing pages. Nothing to configure.
538
+
539
+ Every site also answers \`/llms.txt\` with a list of its pages, generated from
540
+ the deploy unless the folder ships its own. Another agent handed the URL can
541
+ start there; you do not need to write the file.
542
+
521
543
  ## Deeper reference
522
544
 
523
545
  Open these when the task calls for them.
@@ -11,6 +11,14 @@ export interface CommandIO {
11
11
  env?: NodeJS.ProcessEnv;
12
12
  /** Working directory used for folder->site lookup + deploy-dir resolution. */
13
13
  cwd?: string;
14
+ /**
15
+ * True when stdout is a terminal a person is reading. A command then prints
16
+ * for that person: `versions` an aligned table instead of tab-separated
17
+ * rows, and `update` / `rollback` do not repeat on stdout the URL the screen
18
+ * has just shown. Unset (scripts, pipes, every test) keeps stdout exactly
19
+ * what it has always been.
20
+ */
21
+ interactive?: boolean;
14
22
  /** Open a URL in the default browser. Tests inject a no-op. */
15
23
  openUrl?: (url: string) => Promise<void>;
16
24
  /**
@@ -45,6 +53,8 @@ export declare function update(args: {
45
53
  json?: boolean;
46
54
  quiet?: boolean;
47
55
  help?: boolean;
56
+ /** The full receipt instead of the short default. See receipt.ts. */
57
+ verbose?: boolean;
48
58
  }, io: CommandIO): Promise<number>;
49
59
  export declare function versions(args: {
50
60
  site?: string;
@@ -23,13 +23,13 @@ export declare function errorEnvelope(err: CliError): Record<string, unknown>;
23
23
  */
24
24
  export declare function emitError(err: CliError, args: {
25
25
  json?: boolean;
26
- }, io: Pick<CommandIO, "out" | "err">, opts?: {
26
+ }, io: Pick<CommandIO, "out" | "err" | "style">, _opts?: {
27
27
  prefix?: string;
28
28
  }): number;
29
29
  /** Shorthand for the common "build the error, emit it, return the code" line. */
30
30
  export declare function fail(code: ErrorCode, error: string, args: {
31
31
  json?: boolean;
32
- }, io: Pick<CommandIO, "out" | "err">, opts?: {
32
+ }, io: Pick<CommandIO, "out" | "err" | "style">, opts?: {
33
33
  fix?: string;
34
34
  prefix?: string;
35
35
  status?: number;
@@ -59,6 +59,12 @@ export interface ClassifyContext {
59
59
  * otherwise the status decides.
60
60
  */
61
61
  export declare function classifyResponse(res: Response, ctx: ClassifyContext): Promise<CliError>;
62
+ /**
63
+ * No folder to deploy. `resolveDeployDir` throws one long sentence (it is a
64
+ * library function and its message has to stand alone); here it is split into
65
+ * what went wrong and what to do, so the terminal can show them as two things.
66
+ */
67
+ export declare function noBuildDir(message: string): CliError;
62
68
  /** A `fetch` that threw: DNS, refused connection, TLS, timeout. */
63
69
  export declare function networkError(e: unknown, baseUrl?: string): CliError;
64
70
  /** The canonical "nothing is linked here" failure, shared by every verb that targets a site. */
@@ -1,23 +1,9 @@
1
+ import { type ScreenStyle } from "./screen";
1
2
  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
- */
3
+ /** The column budget for every line this module prints. See ./screen.ts. */
14
4
  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;
5
+ /** The style every screen takes. Same thing as the screen vocabulary's. */
6
+ export type TailStyle = ScreenStyle;
21
7
  /** What the terminal actually shows, with color escapes discounted. */
22
8
  export declare function visibleWidth(line: string): number;
23
9
  /** Whole days from `now` until `expiresAt`, floored at 0. */
@@ -41,87 +27,113 @@ export declare function expiryDate(expiresAt: number): string;
41
27
  */
42
28
  export declare function timestamp(ms: number): string;
43
29
  /**
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).
30
+ * When the site ends, and the one command that prevents it — two rows.
31
+ *
32
+ * An expiry that surprises someone is a lost user; an expiry they were told
33
+ * about is a feature. These used to share one line
34
+ * (`19 Oct 2026 · 14 days · flypod login keeps it`), which was compact and
35
+ * left a new user guessing what "keeps it" involved. Separately, the date
36
+ * reads as a fact and `flypod login` gets a hint of its own that answers the
37
+ * two things people hesitate over: what it costs and what it changes.
65
38
  *
66
- * Empty for a site that doesn't expire — an owned site gets no nag anywhere.
39
+ * An owned site gets one row saying it does not end, and no offer.
67
40
  */
68
- export declare function expiryLines(opts: {
41
+ export declare function expiryRows(opts: {
69
42
  expiresAt: number | null;
43
+ owned?: boolean;
70
44
  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 {
45
+ }, style?: TailStyle): string[];
46
+ /**
47
+ * A warning the server attached to a deploy, for a person. Always shown: a
48
+ * deploy that exits 0 and serves a broken site is the one thing a short
49
+ * receipt must not hide. The code is the title (it is what `--json` calls it,
50
+ * so a person and their agent can talk about the same thing) and the fix is
51
+ * wrapped underneath.
52
+ */
53
+ export declare function warningLines(warnings: Array<{
54
+ code: string;
55
+ fix_recipe: string;
56
+ }> | undefined, style?: TailStyle): string[];
57
+ export interface DeployScreenOptions {
58
+ url: string;
80
59
  /** Epoch ms the site expires, or null when it is owned/permanent. */
81
60
  expiresAt: number | null;
82
61
  /** Set when the deploy was attributed to an account. */
83
62
  owned: boolean;
63
+ warnings?: Array<{
64
+ code: string;
65
+ fix_recipe: string;
66
+ }>;
67
+ /** Add the rest of the version loop and the ids. */
68
+ verbose?: boolean;
69
+ /** Shown under `--verbose` only. */
70
+ details?: {
71
+ siteId: string;
72
+ versionId: string;
73
+ source: string;
74
+ };
84
75
  now?: number;
85
76
  style?: TailStyle;
86
77
  }
87
78
  /**
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.
79
+ * The deploy screen, after its `✓ Deployed` line.
80
+ *
81
+ * Top to bottom, in the order a person needs it: the URL, alone and bright,
82
+ * because it is the result; anything that is wrong with the site; then a
83
+ * small grid of what to do next.
84
+ *
85
+ * By default the grid says three things, each of which changes the outcome
86
+ * if it is missed, in the order a first-time user needs them:
87
+ *
88
+ * - when the site ends;
89
+ * - the single command that prevents that, and that it is free;
90
+ * - `flypod update`, because running `flypod` again makes a second site and
91
+ * strands the URL already handed over — the one expensive mistake.
90
92
  *
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.
93
+ * `--verbose` adds rollback and history to the same grid, and the ids below
94
+ * it. It is the same screen with more rows, not a different one: someone who
95
+ * has learned to read the default already knows where everything is.
95
96
  */
96
- export declare function deployTail(opts: TailOptions): string[];
97
+ export declare function deployScreen(opts: DeployScreenOptions): string[];
97
98
  /**
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.
99
+ * The `flypod update` screen: it is live, here it is, how to undo it, and —
100
+ * for a temporary site — when it ends. `flypod rollback` earns its row for the
101
+ * reason `flypod update` earns one after a deploy: it is the next thing
102
+ * someone needs if this went wrong.
105
103
  */
106
- export declare function updateTail(opts: {
104
+ export declare function updateScreen(opts: {
107
105
  versionId: string;
108
106
  url: string;
109
107
  expiresAt: number | null;
110
- /** Whatever survived the deploy, as the server reported it. */
111
108
  warnings?: Array<{
112
109
  code: string;
113
110
  fix_recipe: string;
114
111
  }>;
112
+ verbose?: boolean;
115
113
  now?: number;
116
114
  style?: TailStyle;
117
115
  }): 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. */
116
+ /** What `flypod rollback` says. Lean on purpose: a recovery action, not a place to sell anything. */
120
117
  export declare function rollbackTail(opts: {
121
118
  versionId: string;
122
119
  url: string;
123
120
  style?: TailStyle;
124
121
  }): string[];
122
+ /**
123
+ * `flypod versions` for a person: an aligned table, newest first, with the
124
+ * live one marked. Only used when stdout is a terminal — piped, the command
125
+ * still prints tab-separated rows, which is the scriptable contract.
126
+ */
127
+ export declare function versionsTable(opts: {
128
+ versions: Array<{
129
+ version_id: string;
130
+ created_at: number;
131
+ }>;
132
+ liveVersionId: string;
133
+ expiresAt: number | null;
134
+ now?: number;
135
+ style?: TailStyle;
136
+ }): string[];
125
137
  /**
126
138
  * What to say when `flypod` is run in a folder that already deploys somewhere.
127
139
  *
@@ -137,6 +149,16 @@ export declare function relinkNotice(prev: {
137
149
  site_id: string;
138
150
  url: string;
139
151
  }, style?: TailStyle): string[];
152
+ /**
153
+ * The folder link could not be saved, so the person is the only holder of the
154
+ * site's token (docs/ownership.md). The one moment a token belongs on screen:
155
+ * staying quiet would hand them a live site that can never be updated, rolled
156
+ * back, or kept. The token gets a line to itself so it can be selected cleanly.
157
+ */
158
+ export declare function unsavedLinkNotice(opts: {
159
+ configPath: string;
160
+ manageToken: string;
161
+ }, style?: TailStyle): string[];
140
162
  export interface AgentNextOptions {
141
163
  siteId: string;
142
164
  expiresAt: number | null;
@@ -159,4 +181,16 @@ export interface AgentNextOptions {
159
181
  * Keys are stable and the values are literal commands, not prose: an agent can
160
182
  * execute `next.update` verbatim.
161
183
  */
184
+ /**
185
+ * The `next` commands alone — what the default `--json` receipt carries.
186
+ *
187
+ * The receipt was trimmed for the same reason the terminal tail was, but this
188
+ * part stays: without `next.update` an agent's whole knowledge of flypod after
189
+ * a deploy is "there is a URL", and its next deploy runs the deploy verb again
190
+ * and makes a second site. The prose around it (`next_note`, the expiry
191
+ * restated two more ways) is what `--verbose` adds back.
192
+ */
193
+ export declare function agentNextCommands(opts: AgentNextOptions): {
194
+ next: Record<string, string>;
195
+ };
162
196
  export declare function agentNext(opts: AgentNextOptions): Record<string, unknown>;
@@ -0,0 +1,43 @@
1
+ /**
2
+ * The column budget for every line the CLI prints by itself. Server prose and
3
+ * paths are wrapped to it; a single unbreakable token (a URL, a file path) is
4
+ * the only thing allowed past it. 66 columns reads comfortably and fits the
5
+ * frame the terminal recordings are rendered at.
6
+ */
7
+ export declare const WIDTH = 66;
8
+ /** Width of the label column in the two-column grid. */
9
+ export declare const GUTTER = 10;
10
+ export interface ScreenStyle {
11
+ dim(s: string): string;
12
+ bold(s: string): string;
13
+ muted(s: string): string;
14
+ accent(s: string): string;
15
+ ok(s: string): string;
16
+ /** Optional so older style objects (tests, the tail helpers) still fit. */
17
+ err?(s: string): string;
18
+ warn?(s: string): string;
19
+ }
20
+ export declare const PLAIN: ScreenStyle;
21
+ /** Break prose into lines no wider than `width`. Never splits a word. */
22
+ export declare function wrap(text: string, width: number): string[];
23
+ /** ` ✓ Deployed in 0.9s · 12 files · 1.2 MB` — the detail is quieter than the fact. */
24
+ export declare function headline(text: string, detail: string | undefined, s: ScreenStyle): string;
25
+ /** The result of the command: the one line someone will copy. */
26
+ export declare function hero(url: string, s: ScreenStyle): string;
27
+ /** ` label value hint` — one row of the grid. */
28
+ export declare function field(label: string, value: string, hint: string | undefined, s: ScreenStyle): string;
29
+ /**
30
+ * Something that needs a look but did not stop the command: a warning from the
31
+ * server, a folder that is already linked. A short title on the `!` line and
32
+ * the explanation wrapped beneath it, followed by a blank line so it never
33
+ * runs into the grid below.
34
+ */
35
+ export declare function notice(title: string, body: string, s: ScreenStyle): string[];
36
+ /**
37
+ * The command did not work. The reason on the `✗` line (wrapped, so a long
38
+ * one stays readable), and the next step underneath, dimmer, because it is
39
+ * the thing to do rather than the thing to read first.
40
+ */
41
+ export declare function failure(error: string, fix: string | undefined, s: ScreenStyle): string[];
42
+ /** A version id as shown in a sentence. The full id is in `flypod versions`. */
43
+ export declare function shortVersion(versionId: string): string;
package/dist/src/cli.js CHANGED
@@ -4,7 +4,7 @@ import {
4
4
  collectDist,
5
5
  deploySite,
6
6
  resolveDeployDir
7
- } from "../cli-198a0gkx.js";
7
+ } from "../cli-nqpgfpnm.js";
8
8
  export {
9
9
  BUILD_DIR_CANDIDATES,
10
10
  DeployError,
@@ -15,7 +15,7 @@ export declare const ANON_ID_HEADER = "x-flypod-anon-id";
15
15
  * Without this value in the allowlist the header coerces to `unknown` and stays
16
16
  * in the denominator, which is the silent version of the same mistake.
17
17
  */
18
- export declare const DEPLOY_SOURCES: readonly ["cli", "browser", "library", "skill", "ci", "unknown"];
18
+ export declare const DEPLOY_SOURCES: readonly ["cli", "browser", "library", "skill", "mcp", "ci", "unknown"];
19
19
  export type DeploySource = (typeof DEPLOY_SOURCES)[number];
20
20
  /** Validate a client-supplied source header; anything unrecognized is `unknown`. */
21
21
  export declare function coerceSource(value: string | null | undefined): DeploySource;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "flypod",
3
- "version": "0.10.1",
3
+ "version": "0.11.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",