flypod 0.17.0 → 0.18.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +55 -13
- package/dist/bin/deploy.js +545 -100
- package/dist/{cli-z3p9tds1.js → cli-tydvmnwj.js} +641 -204
- package/dist/src/api-error.d.ts +4 -0
- package/dist/src/cli/agent-env.d.ts +5 -0
- package/dist/src/cli/agent-guide.d.ts +16 -0
- package/dist/src/cli/build-hint.d.ts +13 -0
- package/dist/src/cli/commands.d.ts +4 -0
- package/dist/src/cli/errors.d.ts +84 -2
- package/dist/src/cli/install-id.d.ts +18 -4
- package/dist/src/cli/invoked-via.d.ts +6 -0
- package/dist/src/cli/limits.d.ts +30 -8
- package/dist/src/cli/projects.d.ts +51 -3
- package/dist/src/cli/receipt.d.ts +18 -0
- package/dist/src/cli/skill.d.ts +18 -4
- package/dist/src/cli/source.d.ts +3 -1
- package/dist/src/cli-error-codes.d.ts +28 -0
- package/dist/src/cli.d.ts +15 -3
- package/dist/src/cli.js +1 -1
- package/dist/src/client-meta.d.ts +83 -0
- package/dist/src/ingest-error.d.ts +18 -1
- package/dist/src/upload-shape.d.ts +5 -0
- package/package.json +1 -1
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
export type ApiErrorCode = "bad_request" | "invalid_upload" | "too_large" | "unauthorized" | "login_required" | "token_rejected" | "invalid_origin" | "forbidden" | "challenge_required" | "blocked" | "not_found" | "unknown_version" | "already_claimed" | "invalid_claim" | "expired" | "taken_down" | "rate_limited" | "server_error";
|
|
2
|
+
export declare function apiError(status: number, code: ApiErrorCode, message: string, extra?: Record<string, unknown>): Response;
|
|
3
|
+
/** The code a bare HTTP status implies, for errors raised with a status only. */
|
|
4
|
+
export declare function codeForStatus(status: number): ApiErrorCode;
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
import type { CodingAgent } from "../client-meta";
|
|
2
|
+
/** The coding agent that launched this process, or `none`. First match wins. */
|
|
3
|
+
export declare function detectCodingAgent(env: NodeJS.ProcessEnv): CodingAgent;
|
|
4
|
+
/** True under a CI system. `CI` is the shared convention; GitHub Actions also sets its own. */
|
|
5
|
+
export declare function detectCi(env: NodeJS.ProcessEnv): boolean;
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import type { AgentGuide } from "../client-meta";
|
|
2
|
+
/** The folder the command runs in plus this many parents, at most. */
|
|
3
|
+
export declare const MAX_LEVELS = 4;
|
|
4
|
+
/** Bytes read from the start of each file. */
|
|
5
|
+
export declare const MAX_BYTES: number;
|
|
6
|
+
/**
|
|
7
|
+
* The nearest instruction file naming flypod, from `cwd` up to its repository
|
|
8
|
+
* root. `home` is the home directory, which is never read; tests inject it.
|
|
9
|
+
*/
|
|
10
|
+
export declare function detectAgentGuide(cwd: string, opts?: {
|
|
11
|
+
home?: string;
|
|
12
|
+
}): Promise<AgentGuide>;
|
|
13
|
+
/** `detectAgentGuide`, once per folder per process. */
|
|
14
|
+
export declare function agentGuideFor(cwd: string, opts?: {
|
|
15
|
+
home?: string;
|
|
16
|
+
}): Promise<AgentGuide>;
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
export interface BuildHintOptions {
|
|
2
|
+
/** The verb the fix runs: `flypod` for a first deploy, `flypod update` after. */
|
|
3
|
+
verb: string;
|
|
4
|
+
/** A folder that must not be named: the one that just turned out empty. */
|
|
5
|
+
exclude?: string;
|
|
6
|
+
/** The folder this one deployed last time, named first when it is the answer. */
|
|
7
|
+
remembered?: string;
|
|
8
|
+
}
|
|
9
|
+
/**
|
|
10
|
+
* The fix for "no folder to deploy here", or null when the folder says
|
|
11
|
+
* nothing more specific than the generic advice. Never throws.
|
|
12
|
+
*/
|
|
13
|
+
export declare function buildHint(cwd: string, opts: BuildHintOptions): Promise<string | null>;
|
|
@@ -29,6 +29,8 @@ export interface CommandIO {
|
|
|
29
29
|
* asserting on strings rather than on escape sequences).
|
|
30
30
|
*/
|
|
31
31
|
style?: TailStyle;
|
|
32
|
+
/** Wait before a retry. Defaults to a real timer; tests inject one that does not wait. */
|
|
33
|
+
sleep?: (ms: number) => Promise<void>;
|
|
32
34
|
}
|
|
33
35
|
/**
|
|
34
36
|
* Print help text: always on stdout and always exit 0, for every verb, so
|
|
@@ -61,6 +63,8 @@ export declare function claim(args: {
|
|
|
61
63
|
json?: boolean;
|
|
62
64
|
help?: boolean;
|
|
63
65
|
}, io: CommandIO): Promise<number>;
|
|
66
|
+
/** The pause before `update`'s one retry. */
|
|
67
|
+
export declare const UPDATE_RETRY_MS = 2000;
|
|
64
68
|
export declare function update(args: {
|
|
65
69
|
path?: string;
|
|
66
70
|
site?: string;
|
package/dist/src/cli/errors.d.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
import type { CLI_ERROR_CODES } from "../cli-error-codes";
|
|
1
|
+
import type { CLI_ERROR_CODES, NO_SITE_REASONS, SENT_CREDENTIALS, SERVER_ERROR_ORIGINS, SITE_TARGETS } from "../cli-error-codes";
|
|
2
2
|
import type { CommandIO } from "./commands";
|
|
3
|
-
export { CLI_ERROR_CODES } from "../cli-error-codes";
|
|
3
|
+
export { CLI_ERROR_CODES, NO_SITE_REASONS } from "../cli-error-codes";
|
|
4
4
|
/**
|
|
5
5
|
* Every code a CLI failure can carry, grouped in `CLI_ERROR_CODES` by where it
|
|
6
6
|
* comes from. The list is a value in its own module so the control plane can
|
|
@@ -62,7 +62,32 @@ export declare function readServerMessage(res: Response): Promise<{
|
|
|
62
62
|
fix?: string;
|
|
63
63
|
/** Which limit a 413 hit (`files`, `total_bytes`, …), when the server said. */
|
|
64
64
|
limit?: string;
|
|
65
|
+
/** The control plane's id for this request, which its 500 asks to be quoted. */
|
|
66
|
+
requestId?: string;
|
|
67
|
+
/** Cloudflare's own error number (1101, 1102, …) from a page the platform wrote. */
|
|
68
|
+
cfError?: number;
|
|
65
69
|
}>;
|
|
70
|
+
/**
|
|
71
|
+
* The number on an error page Cloudflare wrote itself: `error code: 1102` (the
|
|
72
|
+
* plain-text body a non-browser client gets) or `Error 1102` (the HTML page).
|
|
73
|
+
* Only the 1xxx range, which is Cloudflare's own; any other number in a body
|
|
74
|
+
* is not a code we can name.
|
|
75
|
+
*/
|
|
76
|
+
export declare function cloudflareErrorNumber(text: string): number | undefined;
|
|
77
|
+
/**
|
|
78
|
+
* Who wrote a 5xx: flypod's control plane (`app`: a JSON body, which every
|
|
79
|
+
* control-plane error is, src/api-error.ts) or something in front of it
|
|
80
|
+
* (`edge`: Cloudflare's own page when the Worker threw past the app or ran out
|
|
81
|
+
* of CPU or memory, a gateway error, or an empty body).
|
|
82
|
+
*
|
|
83
|
+
* Why it is worth a word: in the week of 2026-10-19 the CLI reported 663
|
|
84
|
+
* `server_error`s on `update` while the server recorded 56 `deploy_failed`
|
|
85
|
+
* with that code. The server can only record answers its own error handler
|
|
86
|
+
* wrote, so the gap is answers the app never wrote, and the report had no way
|
|
87
|
+
* to say so. The code stays `server_error` either way (agents branch on it,
|
|
88
|
+
* and both are retryable); the word goes in the failure report only.
|
|
89
|
+
*/
|
|
90
|
+
export type ServerErrorOrigin = (typeof SERVER_ERROR_ORIGINS)[number];
|
|
66
91
|
export interface ClassifyContext {
|
|
67
92
|
/** `flypod update`, `flypod comments post`, … — for the human prefix. */
|
|
68
93
|
verb: string;
|
|
@@ -83,8 +108,19 @@ export interface ClassifyContext {
|
|
|
83
108
|
* better answer reach every installed CLI without waiting for an upgrade.
|
|
84
109
|
*/
|
|
85
110
|
export declare function classifyResponse(res: Response, ctx: ClassifyContext): Promise<CliError>;
|
|
111
|
+
/**
|
|
112
|
+
* The fix on a 401 when nothing more is known. The version verbs replace it
|
|
113
|
+
* with `unauthorizedFor`, which knows what credential was sent.
|
|
114
|
+
*/
|
|
115
|
+
export declare const UNAUTHORIZED_FIX = "Run `flypod login`, or pass --token <manage_token> for a site this machine does not remember.";
|
|
86
116
|
/** The limits a `too_large` can name, in the CLI's precheck and in a report. */
|
|
87
117
|
export declare const SIZE_LIMITS: readonly ["files", "total_bytes", "zip_bytes"];
|
|
118
|
+
/**
|
|
119
|
+
* A 5xx, worded for who wrote it. Always `server_error` (exit 4); the failure
|
|
120
|
+
* report also gets `origin` and, from a Cloudflare page, `cf_error`, so the
|
|
121
|
+
* growth report can tell our own 500s from the platform's.
|
|
122
|
+
*/
|
|
123
|
+
export declare function serverError(status: number, said: Awaited<ReturnType<typeof readServerMessage>>, verb: string): CliError;
|
|
88
124
|
/**
|
|
89
125
|
* No folder to deploy. `resolveDeployDir` throws one long sentence (it is a
|
|
90
126
|
* library function and its message has to stand alone); here it is split into
|
|
@@ -95,6 +131,52 @@ export declare function noBuildDir(message: string): CliError;
|
|
|
95
131
|
export declare function networkError(e: unknown, baseUrl?: string): CliError;
|
|
96
132
|
/** The canonical "nothing is linked here" failure, shared by every verb that targets a site. */
|
|
97
133
|
export declare const NO_SITE: CliError;
|
|
134
|
+
/** Why a folder has no site, as `reason` in the `no_site` envelope. */
|
|
135
|
+
export type NoSiteReason = (typeof NO_SITE_REASONS)[number];
|
|
136
|
+
type SentCredential = (typeof SENT_CREDENTIALS)[number];
|
|
137
|
+
export type SiteTarget = (typeof SITE_TARGETS)[number];
|
|
138
|
+
/**
|
|
139
|
+
* `no_site` for the version verbs (`update`, `versions`, `rollback`), told
|
|
140
|
+
* apart by what this machine remembers about the folder. It was one sentence
|
|
141
|
+
* for all of them ("No flypod site is linked to this folder"), so the person
|
|
142
|
+
* whose temporary site had expired on day 14 was told the folder had never
|
|
143
|
+
* been deployed, and an agent could not tell "make the site" from "it is
|
|
144
|
+
* gone" from "you are one folder off". The code stays `no_site`; `reason`
|
|
145
|
+
* says which (NO_SITE_REASONS), and `fix` is the one command for it.
|
|
146
|
+
*/
|
|
147
|
+
export declare function noSite(ctx: {
|
|
148
|
+
/** `update`, `versions`, `rollback`. */
|
|
149
|
+
verb: string;
|
|
150
|
+
gone?: {
|
|
151
|
+
site_id: string;
|
|
152
|
+
url: string;
|
|
153
|
+
reason: "expired" | "gone";
|
|
154
|
+
at: number;
|
|
155
|
+
} | null;
|
|
156
|
+
nearby?: {
|
|
157
|
+
dir: string;
|
|
158
|
+
site_id: string;
|
|
159
|
+
} | null;
|
|
160
|
+
signedIn?: boolean;
|
|
161
|
+
}): CliError;
|
|
162
|
+
/**
|
|
163
|
+
* `unauthorized` on a site-scoped request, with the fix that matches the
|
|
164
|
+
* credential this machine sent. The server answers 401 alike for a site
|
|
165
|
+
* that no longer exists, a site kept by an account, and a wrong token (a
|
|
166
|
+
* site id is public; which of those it is, is not), so the CLI says what it
|
|
167
|
+
* knows: what it sent. 15 people in a week got "Run `flypod login`, or pass
|
|
168
|
+
* --token <manage_token>", which fit none of them.
|
|
169
|
+
*/
|
|
170
|
+
export declare function unauthorizedFor(ctx: {
|
|
171
|
+
siteId: string;
|
|
172
|
+
/** What authorized the request: `--token`, this folder's manage token, an account, or nothing. */
|
|
173
|
+
sent: SentCredential;
|
|
174
|
+
/** Whether this machine has any record of the site. */
|
|
175
|
+
known: boolean;
|
|
176
|
+
/** How the command named the site. */
|
|
177
|
+
target: SiteTarget;
|
|
178
|
+
status?: number;
|
|
179
|
+
}): CliError;
|
|
98
180
|
export declare const NOT_SIGNED_IN: CliError;
|
|
99
181
|
/** Message for `main().catch` and any other last-resort handler. */
|
|
100
182
|
export declare function unexpectedError(e: unknown): CliError;
|
|
@@ -2,6 +2,10 @@ export declare const INSTALL_HEADER = "x-flypod-install";
|
|
|
2
2
|
export declare const INSTALL_NEW_HEADER = "x-flypod-install-new";
|
|
3
3
|
export declare const VERSION_HEADER = "x-flypod-version";
|
|
4
4
|
export declare const RELINK_HEADER = "x-flypod-relink";
|
|
5
|
+
export declare const AGENT_HEADER = "x-flypod-agent";
|
|
6
|
+
export declare const CI_HEADER = "x-flypod-ci";
|
|
7
|
+
export declare const INVOKED_VIA_HEADER = "x-flypod-invoked-via";
|
|
8
|
+
export declare const AGENT_GUIDE_HEADER = "x-flypod-agent-guide";
|
|
5
9
|
/**
|
|
6
10
|
* True when the user asked not to be counted. `DO_NOT_TRACK` counts when set
|
|
7
11
|
* to anything but an explicit "no" (`""`, `0`, `false`), because the
|
|
@@ -25,11 +29,21 @@ export declare function installId(env?: NodeJS.ProcessEnv): Promise<InstallId |
|
|
|
25
29
|
export declare function setCliVersion(v: string): void;
|
|
26
30
|
export declare function cliVersion(): string | undefined;
|
|
27
31
|
/**
|
|
28
|
-
* The headers that say which install and which CLI version is calling
|
|
29
|
-
*
|
|
30
|
-
*
|
|
32
|
+
* The headers that say which install and which CLI version is calling,
|
|
33
|
+
* whether a coding agent or a CI system is running it (./agent-env.ts), how
|
|
34
|
+
* the CLI was launched (./invoked-via.ts) and whether the project's agent
|
|
35
|
+
* instructions name flypod (./agent-guide.ts). The version is not identifying
|
|
36
|
+
* and is always sent (when known); everything else follows the opt-out,
|
|
37
|
+
* because "which agent does this person use" is a fact about them, not about
|
|
38
|
+
* the CLI.
|
|
39
|
+
*
|
|
40
|
+
* `cwd` is the folder the command runs in (the project), `script` the path
|
|
41
|
+
* the runtime was started with; both default to this process's own.
|
|
31
42
|
*/
|
|
32
|
-
export declare function identityHeaders(env: NodeJS.ProcessEnv
|
|
43
|
+
export declare function identityHeaders(env: NodeJS.ProcessEnv, opts?: {
|
|
44
|
+
cwd?: string;
|
|
45
|
+
script?: string;
|
|
46
|
+
}): Promise<Record<string, string>>;
|
|
33
47
|
/**
|
|
34
48
|
* The one line a person sees the first time an id is made, so being counted
|
|
35
49
|
* is never a surprise. One line because the default output is short, and it
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
import type { InvokedVia } from "../client-meta";
|
|
2
|
+
/**
|
|
3
|
+
* The launch, as one word. `script` is the script path the runtime was given
|
|
4
|
+
* (`process.argv[1]`), `cwd` the folder the command was run in. Never throws.
|
|
5
|
+
*/
|
|
6
|
+
export declare function detectInvokedVia(env: NodeJS.ProcessEnv, script: string | undefined, cwd: string): InvokedVia;
|
package/dist/src/cli/limits.d.ts
CHANGED
|
@@ -13,17 +13,39 @@ export declare function uploadReport(files: Record<string, Uint8Array>, skippedC
|
|
|
13
13
|
* The fix is `sizeAdvice` when the upload's shape says something specific
|
|
14
14
|
* (a project root instead of its build folder, source maps, video): "remove
|
|
15
15
|
* the largest files" was true of every one of them and got none deployed.
|
|
16
|
+
*
|
|
17
|
+
* When the folder can take a .flypodignore (`opts.ignoreFile`, its path as the
|
|
18
|
+
* user would type it), the fix also names the lines that would bring the
|
|
19
|
+
* upload under the limit: the biggest video files for a video-heavy build, the
|
|
20
|
+
* biggest images for an image-heavy one, the folder holding most of the files
|
|
21
|
+
* when there are too many. "Leave unused ones out" left 59 image-heavy uploads
|
|
22
|
+
* in a week to work out which ones. Names stay on the user's screen: the
|
|
23
|
+
* failure report carries the shape only (`uploadReport`).
|
|
24
|
+
*/
|
|
25
|
+
export declare function checkUploadSize(files: Record<string, Uint8Array>, limits: UploadLimits | null, skippedCount?: number, opts?: {
|
|
26
|
+
ignoreFile?: string;
|
|
27
|
+
}): CliError | null;
|
|
28
|
+
/**
|
|
29
|
+
* Where the .flypodignore for a deploy of `dir` goes, as the user would type
|
|
30
|
+
* it from `cwd`, or undefined when `dir` is a single file (which is never
|
|
31
|
+
* filtered, so an ignore file would change nothing).
|
|
16
32
|
*/
|
|
17
|
-
export declare function
|
|
33
|
+
export declare function ignoreFilePath(dir: string, cwd: string): Promise<string | undefined>;
|
|
18
34
|
/**
|
|
19
35
|
* Sharpen a `no_build_dir` / `no_files` failure with what the current folder
|
|
20
|
-
* looks like
|
|
21
|
-
*
|
|
22
|
-
*
|
|
23
|
-
* files" made people guess which one.
|
|
24
|
-
* report either way. Never throws,
|
|
36
|
+
* looks like, so the fix is the literal next command (./build-hint.ts): the
|
|
37
|
+
* build command and the folder it writes for an unbuilt project, the folder
|
|
38
|
+
* that already holds a site, or the Next.js setting that makes static files.
|
|
39
|
+
* The generic "pass the folder of built files" made people guess which one.
|
|
40
|
+
* Adds the folder markers to the failure report either way. Never throws,
|
|
41
|
+
* never makes the error worse.
|
|
25
42
|
*
|
|
26
43
|
* `deployed` is the folder that turned out empty (for `no_files`), so the fix
|
|
27
|
-
* never names the folder that just failed.
|
|
44
|
+
* never names the folder that just failed. `verb` is the command the fix
|
|
45
|
+
* runs (`flypod update` keeps the site), and `remembered` the folder this one
|
|
46
|
+
* deployed last time, named first.
|
|
28
47
|
*/
|
|
29
|
-
export declare function withFolderHint(err: CliError, cwd: string, deployed?: string
|
|
48
|
+
export declare function withFolderHint(err: CliError, cwd: string, deployed?: string, opts?: {
|
|
49
|
+
verb?: string;
|
|
50
|
+
remembered?: string;
|
|
51
|
+
}): Promise<CliError>;
|
|
@@ -15,6 +15,30 @@ export interface ProjectRecord {
|
|
|
15
15
|
last_used: number;
|
|
16
16
|
/** Last version we know is live here — lets `update` detect a no-op. */
|
|
17
17
|
version_id?: string;
|
|
18
|
+
/**
|
|
19
|
+
* The folder (or file) this link last deployed, as an absolute path.
|
|
20
|
+
* `flypod update` with no path deploys it again. Without it, `update`
|
|
21
|
+
* auto-detected a build folder, so a site first deployed with
|
|
22
|
+
* `flypod ./site` (or any folder not on the candidate list) could be
|
|
23
|
+
* updated only by repeating the path, and the receipt's `next.update`
|
|
24
|
+
* (`flypod update`) failed with `no_build_dir`.
|
|
25
|
+
*/
|
|
26
|
+
deploy_dir?: string;
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* What became of a folder's link after it was dropped, so `update` in that
|
|
30
|
+
* folder can say "the site expired" instead of "nothing is linked here".
|
|
31
|
+
* The link of an expired anonymous site used to vanish on the next load, and
|
|
32
|
+
* the person who came back on day 15 was told their folder had never been
|
|
33
|
+
* deployed.
|
|
34
|
+
*/
|
|
35
|
+
export interface GoneLink {
|
|
36
|
+
site_id: string;
|
|
37
|
+
url: string;
|
|
38
|
+
/** `expired`: its 14-day life ran out. `gone`: the server said it no longer exists. */
|
|
39
|
+
reason: "expired" | "gone";
|
|
40
|
+
/** Epoch ms it expired or was found gone. */
|
|
41
|
+
at: number;
|
|
18
42
|
}
|
|
19
43
|
/** Hard cap on remembered projects — keeps projects.json bounded forever. */
|
|
20
44
|
export declare const MAX_PROJECTS = 64;
|
|
@@ -24,7 +48,15 @@ export declare const MAX_PROJECTS = 64;
|
|
|
24
48
|
*/
|
|
25
49
|
export declare function loadProjects(env?: NodeJS.ProcessEnv): Promise<Record<string, ProjectRecord>>;
|
|
26
50
|
/** Persist the registry, pruning expired entries and LRU-capping the size. */
|
|
27
|
-
export declare function saveProjects(projects: Record<string, ProjectRecord>, env?: NodeJS.ProcessEnv
|
|
51
|
+
export declare function saveProjects(projects: Record<string, ProjectRecord>, env?: NodeJS.ProcessEnv,
|
|
52
|
+
/** Folders whose link is being dropped because the server said the site is gone. */
|
|
53
|
+
goneNow?: Record<string, ProjectRecord>): Promise<string>;
|
|
54
|
+
/**
|
|
55
|
+
* Why `dir` has no link any more, when it had one: its site expired (the link
|
|
56
|
+
* is still in the file, or was moved to the tombstones), or the server said it
|
|
57
|
+
* was gone. Null when the folder was never linked, or was forgotten on purpose.
|
|
58
|
+
*/
|
|
59
|
+
export declare function goneForDir(dir: string, env?: NodeJS.ProcessEnv): Promise<GoneLink | null>;
|
|
28
60
|
/**
|
|
29
61
|
* Key prefix for a record no folder points at any more. Registry keys are
|
|
30
62
|
* otherwise absolute directories, so `detached:<site_id>` can never collide
|
|
@@ -53,7 +85,23 @@ export declare function projectForDir(dir: string, env?: NodeJS.ProcessEnv): Pro
|
|
|
53
85
|
* of a site whose folder has since been pointed somewhere else.
|
|
54
86
|
*/
|
|
55
87
|
export declare function projectForSite(site_id: string, env?: NodeJS.ProcessEnv): Promise<ProjectRecord | null>;
|
|
56
|
-
/**
|
|
57
|
-
|
|
88
|
+
/**
|
|
89
|
+
* Forget the link for a directory. Returns whether anything was removed.
|
|
90
|
+
* With `gone`, the server said the site no longer exists, and the folder
|
|
91
|
+
* remembers that so its next command can say so.
|
|
92
|
+
*/
|
|
93
|
+
export declare function forgetDir(dir: string, env?: NodeJS.ProcessEnv, opts?: {
|
|
94
|
+
gone?: boolean;
|
|
95
|
+
}): Promise<boolean>;
|
|
96
|
+
/**
|
|
97
|
+
* The nearest linked folder above or below `dir`, or null. An agent that
|
|
98
|
+
* deployed from the repo root and now runs `flypod update` inside `dist/`
|
|
99
|
+
* (or the other way round) gets `no_site`; this is the folder to name.
|
|
100
|
+
* Below counts only when exactly one linked folder is there.
|
|
101
|
+
*/
|
|
102
|
+
export declare function nearbyLink(dir: string, env?: NodeJS.ProcessEnv): Promise<{
|
|
103
|
+
dir: string;
|
|
104
|
+
rec: ProjectRecord;
|
|
105
|
+
} | null>;
|
|
58
106
|
/** Forget every link pointing at a site id. Returns how many were removed. */
|
|
59
107
|
export declare function forgetSite(site_id: string, env?: NodeJS.ProcessEnv): Promise<number>;
|
|
@@ -149,6 +149,24 @@ export declare function relinkNotice(prev: {
|
|
|
149
149
|
site_id: string;
|
|
150
150
|
url: string;
|
|
151
151
|
}, style?: TailStyle): string[];
|
|
152
|
+
/** The warning code a `--json` receipt carries when `flypod` ran in a linked folder. */
|
|
153
|
+
export declare const RELINK_WARNING = "new-site-in-linked-folder";
|
|
154
|
+
/**
|
|
155
|
+
* The same fact for a caller that reads `warnings` and acts on `fix_recipe`:
|
|
156
|
+
* an agent loop. Worded so that loop does not redeploy (the deploy is fine and
|
|
157
|
+
* live) and learns the one thing that changes its next run.
|
|
158
|
+
*/
|
|
159
|
+
export declare function relinkWarning(prev: {
|
|
160
|
+
site_id: string;
|
|
161
|
+
url: string;
|
|
162
|
+
}, newUrl: string): {
|
|
163
|
+
code: string;
|
|
164
|
+
fix_recipe: string;
|
|
165
|
+
};
|
|
166
|
+
/** The one-line form, for `-q`, which otherwise says nothing on stderr. */
|
|
167
|
+
export declare function relinkHint(prev: {
|
|
168
|
+
url: string;
|
|
169
|
+
}): string;
|
|
152
170
|
/**
|
|
153
171
|
* What a deploy left out (see `collectFiles` in ../cli.ts). Said every time,
|
|
154
172
|
* because a file that silently is not there reads as a broken site; and said
|
package/dist/src/cli/skill.d.ts
CHANGED
|
@@ -89,12 +89,26 @@ export declare function legacyArtifacts(root: string): Promise<string[]>;
|
|
|
89
89
|
* the only evidence that exists on the user's machine: the skill files the
|
|
90
90
|
* command itself writes.
|
|
91
91
|
*
|
|
92
|
-
* Used for deploy attribution (see
|
|
93
|
-
*
|
|
94
|
-
*
|
|
95
|
-
* explicit `FLYPOD_SOURCE` override instead.
|
|
92
|
+
* Used for deploy attribution (see ./source.ts). Project-scoped; a machine-wide
|
|
93
|
+
* install is `skillInstalledGlobally`, which ./source.ts trusts only when the
|
|
94
|
+
* run itself looks like an agent's.
|
|
96
95
|
*/
|
|
97
96
|
export declare function skillInstalledIn(root: string): Promise<boolean>;
|
|
97
|
+
/**
|
|
98
|
+
* The skill directories a machine-wide install can land in, under the home
|
|
99
|
+
* directory. The first two are what `flypod install skill --global` writes
|
|
100
|
+
* (`TARGETS`); the rest are where `npx skills add` and the agents' own skill
|
|
101
|
+
* managers put a user-level skill for Codex, Cursor, Gemini CLI, Copilot and
|
|
102
|
+
* opencode. A stat each, and only on a run that already looks like an agent's.
|
|
103
|
+
*/
|
|
104
|
+
export declare function globalSkillDirs(env: NodeJS.ProcessEnv): string[];
|
|
105
|
+
/**
|
|
106
|
+
* Has the flypod skill been installed for this user rather than for one
|
|
107
|
+
* project? Until 2026-10-26 these were invisible: every deploy taught by a
|
|
108
|
+
* `--global` install (or `npx skills add`) read `source: cli`, and the skill
|
|
109
|
+
* channel read zero.
|
|
110
|
+
*/
|
|
111
|
+
export declare function skillInstalledGlobally(env: NodeJS.ProcessEnv): Promise<boolean>;
|
|
98
112
|
export type WriteStatus = "created" | "updated" | "unchanged";
|
|
99
113
|
export interface WriteResult {
|
|
100
114
|
target: Target;
|
package/dist/src/cli/source.d.ts
CHANGED
|
@@ -4,4 +4,6 @@ import { type DeploySource } from "../deploy-source";
|
|
|
4
4
|
* is the truth for a plain terminal invocation. Never throws: an unreadable
|
|
5
5
|
* project must not be able to fail a deploy.
|
|
6
6
|
*/
|
|
7
|
-
export declare function resolveCliSource(env: NodeJS.ProcessEnv, cwd: string
|
|
7
|
+
export declare function resolveCliSource(env: NodeJS.ProcessEnv, cwd: string, opts?: {
|
|
8
|
+
stdoutIsTTY?: boolean;
|
|
9
|
+
}): Promise<DeploySource>;
|
|
@@ -6,3 +6,31 @@ export declare const CLI_ERROR_CODES: readonly ["usage", "unknown_command", "unk
|
|
|
6
6
|
* `--help` and a deploy path are not verbs: a failed deploy reports `deploy`.
|
|
7
7
|
*/
|
|
8
8
|
export declare const CLI_VERBS: readonly ["deploy", "update", "versions", "rollback", "forget", "token", "login", "logout", "list", "claim", "install", "comments"];
|
|
9
|
+
/**
|
|
10
|
+
* Who wrote the answer behind a `server_error`, as the failure report's
|
|
11
|
+
* `origin` (src/cli/errors.ts `serverError`): `app` is flypod's control plane
|
|
12
|
+
* (a JSON body), `edge` is something in front of it (Cloudflare's own page, a
|
|
13
|
+
* gateway error, an empty body), and `unreadable` is a success status whose
|
|
14
|
+
* body could not be read to the end.
|
|
15
|
+
*/
|
|
16
|
+
export declare const SERVER_ERROR_ORIGINS: readonly ["app", "edge", "unreadable"];
|
|
17
|
+
/**
|
|
18
|
+
* Why a version verb found no site (`reason` on a `no_site` failure, in the
|
|
19
|
+
* `--json` envelope and the failure report): the folder was never linked, its
|
|
20
|
+
* site expired, the server said it was gone, or a folder above or below this
|
|
21
|
+
* one is the linked one.
|
|
22
|
+
*/
|
|
23
|
+
export declare const NO_SITE_REASONS: readonly ["never_linked", "expired", "gone", "other_folder"];
|
|
24
|
+
/**
|
|
25
|
+
* Which credential an `unauthorized` site request carried (`credential` in the
|
|
26
|
+
* failure report): `--token`, the folder's manage token, an account, or none.
|
|
27
|
+
*/
|
|
28
|
+
export declare const SENT_CREDENTIALS: readonly ["flag", "manage_token", "account", "none"];
|
|
29
|
+
/**
|
|
30
|
+
* How an `unauthorized` site request named its site (`target` in the failure
|
|
31
|
+
* report, beside the `known` flag): this folder's link (`link`), or
|
|
32
|
+
* `--site <id>` (`flag`). The week of 2026-10-26 had 30 `unauthorized` on
|
|
33
|
+
* `update` with `credential: none`, all from Cursor installs, and nothing said
|
|
34
|
+
* whether those machines had ever held the site or were handed its id.
|
|
35
|
+
*/
|
|
36
|
+
export declare const SITE_TARGETS: readonly ["link", "flag"];
|
package/dist/src/cli.d.ts
CHANGED
|
@@ -7,9 +7,21 @@ export type { DeploySource } from "./deploy-source";
|
|
|
7
7
|
*/
|
|
8
8
|
export declare const BUILD_DIR_CANDIDATES: string[];
|
|
9
9
|
/**
|
|
10
|
-
* Resolve the directory to deploy. An explicit path is used verbatim.
|
|
11
|
-
*
|
|
12
|
-
*
|
|
10
|
+
* Resolve the directory to deploy. An explicit path is used verbatim.
|
|
11
|
+
* Otherwise, in order:
|
|
12
|
+
*
|
|
13
|
+
* 1. the first candidate build folder that exists and contains an index.html,
|
|
14
|
+
* so `npx flypod` (no argument) just works from a project root;
|
|
15
|
+
* 2. a candidate folder whose only site is one level down (`dist/<app>/` or
|
|
16
|
+
* `dist/<app>/browser/`, as Angular builds), when exactly one is there;
|
|
17
|
+
* 3. the folder itself, when it has an index.html, no package.json (or other
|
|
18
|
+
* project file such as `_config.yml` or `pyproject.toml`), and is not the
|
|
19
|
+
* home directory: a folder of hand-written pages, which is what an agent
|
|
20
|
+
* asked for "a page" leaves behind. It used to fail with `no_build_dir`
|
|
21
|
+
* while the site sat right there.
|
|
22
|
+
*
|
|
23
|
+
* A project root is never deployed by this function: its index.html, when it
|
|
24
|
+
* has one, is the source template (Vite), and node_modules is beside it.
|
|
13
25
|
*/
|
|
14
26
|
export declare function resolveDeployDir(opts?: {
|
|
15
27
|
cwd?: string;
|
package/dist/src/cli.js
CHANGED
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
export declare const INSTALL_HEADER = "x-flypod-install";
|
|
2
|
+
export declare const INSTALL_NEW_HEADER = "x-flypod-install-new";
|
|
3
|
+
export declare const VERSION_HEADER = "x-flypod-version";
|
|
4
|
+
export declare const RELINK_HEADER = "x-flypod-relink";
|
|
5
|
+
export declare const AGENT_HEADER = "x-flypod-agent";
|
|
6
|
+
export declare const CI_HEADER = "x-flypod-ci";
|
|
7
|
+
export declare const INVOKED_VIA_HEADER = "x-flypod-invoked-via";
|
|
8
|
+
export declare const AGENT_GUIDE_HEADER = "x-flypod-agent-guide";
|
|
9
|
+
/**
|
|
10
|
+
* Which coding agent ran the CLI, as one of these words and nothing else. The
|
|
11
|
+
* CLI reads it from environment variables the agents themselves set
|
|
12
|
+
* (src/cli/agent-env.ts) and sends the word, never a variable's value.
|
|
13
|
+
*
|
|
14
|
+
* Why it exists: 85% of the week of 2026-10-26's deploys read `source: cli`
|
|
15
|
+
* and most of those deployers never opened the website, so whether they were
|
|
16
|
+
* people at a terminal or agents working for them was a guess. `source` cannot
|
|
17
|
+
* carry the answer, because it names *our* surface and a skill-taught agent is
|
|
18
|
+
* still running the CLI.
|
|
19
|
+
*
|
|
20
|
+
* `other` is a tool that announces itself through the `AI_AGENT` convention
|
|
21
|
+
* with a name not on this list; `none` is a run with no agent in sight.
|
|
22
|
+
*/
|
|
23
|
+
export declare const CODING_AGENTS: readonly ["claude_code", "codex", "cursor", "gemini", "opencode", "other", "none"];
|
|
24
|
+
export type CodingAgent = (typeof CODING_AGENTS)[number];
|
|
25
|
+
/**
|
|
26
|
+
* How the CLI was launched, as one of these words and nothing else
|
|
27
|
+
* (src/cli/invoked-via.ts reads it from the package manager's environment and
|
|
28
|
+
* the shape of the script's own path, and sends only the word).
|
|
29
|
+
*
|
|
30
|
+
* Why it exists: on 2026-11-01, 75% of new deployers ran flypod under Cursor
|
|
31
|
+
* while the website saw about 58 visitors a week and `source: skill` read 0,
|
|
32
|
+
* so nobody could say how those people came to have flypod at all. A fetch
|
|
33
|
+
* per run (`npx`, `bunx`, `pnpm_dlx`, `yarn_dlx`) is someone or something
|
|
34
|
+
* typing the documented one-liner; `local` is a project dependency, `script`
|
|
35
|
+
* a package.json script that calls it, `global` an install on the machine.
|
|
36
|
+
* `other` is anything else (a checkout run from source, an unusual layout).
|
|
37
|
+
*/
|
|
38
|
+
export declare const INVOKED_VIA: readonly ["npx", "bunx", "pnpm_dlx", "yarn_dlx", "script", "local", "global", "other"];
|
|
39
|
+
export type InvokedVia = (typeof INVOKED_VIA)[number];
|
|
40
|
+
/**
|
|
41
|
+
* Which agent-instruction file in the project names flypod, as one of these
|
|
42
|
+
* words (src/cli/agent-guide.ts; never a file's content or name). `skill` is
|
|
43
|
+
* a flypod skill in the project (the same test as `source: skill`); `none` is
|
|
44
|
+
* a project whose instruction files, if it has any, never say "flypod".
|
|
45
|
+
*
|
|
46
|
+
* Why it exists: the same 2026-11-01 review. An agent that deploys with
|
|
47
|
+
* flypod either was told to by the project (one of these files) or found it
|
|
48
|
+
* on its own; the two need different work from us, and nothing said which.
|
|
49
|
+
*/
|
|
50
|
+
export declare const AGENT_GUIDES: readonly ["skill", "agents_md", "claude_md", "cursor_rules", "copilot", "gemini_md", "none"];
|
|
51
|
+
export type AgentGuide = (typeof AGENT_GUIDES)[number];
|
|
52
|
+
export interface ClientMeta {
|
|
53
|
+
install_id?: string;
|
|
54
|
+
/** Only on requests from the process that created the install id. */
|
|
55
|
+
install_new?: true;
|
|
56
|
+
cli_version?: string;
|
|
57
|
+
/** The folder was already linked to a site when this `POST /sites` was made. */
|
|
58
|
+
relinked?: true;
|
|
59
|
+
/** The coding agent that ran the CLI (`none` for none); absent from older CLIs. */
|
|
60
|
+
coding_agent?: CodingAgent;
|
|
61
|
+
/** The CLI ran under a CI system (`CI`, `GITHUB_ACTIONS`, …); absent from older CLIs. */
|
|
62
|
+
ci?: boolean;
|
|
63
|
+
/** How the CLI was launched (`npx`, `global`, …); absent from older CLIs. */
|
|
64
|
+
invoked_via?: InvokedVia;
|
|
65
|
+
/** Which instruction file in the project names flypod (`none` for none); absent from older CLIs. */
|
|
66
|
+
agent_guide?: AgentGuide;
|
|
67
|
+
}
|
|
68
|
+
/**
|
|
69
|
+
* The valid subset of the CLI's headers. Each is checked on its own and an
|
|
70
|
+
* invalid one is dropped, never the request: these are measurement, and a
|
|
71
|
+
* deploy must not fail because a header was malformed.
|
|
72
|
+
*
|
|
73
|
+
* `install_new` without a valid `install_id` is dropped too: "this id is new"
|
|
74
|
+
* means nothing with no id beside it.
|
|
75
|
+
*/
|
|
76
|
+
export declare function clientMeta(headers: Headers): ClientMeta;
|
|
77
|
+
/**
|
|
78
|
+
* The properties `event` gets from these headers. `relinked` belongs to
|
|
79
|
+
* `site_deployed` alone: it describes why a new site was made (a folder that
|
|
80
|
+
* already had one), and on any other event it would read as a fact about that
|
|
81
|
+
* event instead.
|
|
82
|
+
*/
|
|
83
|
+
export declare function clientMetaProps(headers: Headers, event: string): Record<string, unknown>;
|
|
@@ -3,6 +3,7 @@
|
|
|
3
3
|
* two modules importing each other. Nothing else about them changed, and
|
|
4
4
|
* `deploy-pipeline.ts` still re-exports both so existing imports keep working.
|
|
5
5
|
*/
|
|
6
|
+
import type { ApiErrorCode } from "./api-error";
|
|
6
7
|
/** Which of the upload caps a 413 is about. Each names one `UploadLimits` field (or the JSON cap). */
|
|
7
8
|
export type UploadLimitKind = "files" | "total_bytes" | "zip_bytes" | "json_bytes";
|
|
8
9
|
/**
|
|
@@ -35,8 +36,24 @@ export interface TooLargeDetail {
|
|
|
35
36
|
export declare class IngestError extends Error {
|
|
36
37
|
status: number;
|
|
37
38
|
detail?: TooLargeDetail | undefined;
|
|
38
|
-
|
|
39
|
+
/** The API code, when the status alone would name the wrong one. */
|
|
40
|
+
code?: ApiErrorCode | undefined;
|
|
41
|
+
constructor(message: string, status: number, detail?: TooLargeDetail | undefined,
|
|
42
|
+
/** The API code, when the status alone would name the wrong one. */
|
|
43
|
+
code?: ApiErrorCode | undefined);
|
|
39
44
|
}
|
|
45
|
+
/**
|
|
46
|
+
* The upload stopped arriving: the request body's stream failed partway,
|
|
47
|
+
* which is what a caller that gave up mid-upload (a timeout, a killed agent,
|
|
48
|
+
* a dropped connection) looks like from here.
|
|
49
|
+
*
|
|
50
|
+
* It used to escape as a thrown read error and be answered, and recorded, as
|
|
51
|
+
* a `500 server_error`: our fault, in a week when the report was trying to
|
|
52
|
+
* work out which `server_error`s were. Nobody is left to read the answer; the
|
|
53
|
+
* point is what `deploy_failed` says, so it is a `400 bad_request`, apart
|
|
54
|
+
* from the `invalid_upload` of a body that arrived whole and was wrong.
|
|
55
|
+
*/
|
|
56
|
+
export declare function uploadInterrupted(): IngestError;
|
|
40
57
|
/** A byte count the way a person reads a limit: "50 MB", "12.5 MB", "800 KB". */
|
|
41
58
|
export declare function formatBytes(n: number): string;
|
|
42
59
|
/**
|
|
@@ -50,3 +50,8 @@ export declare function shapeProps(shape: UploadShape, markers?: FolderMarkers):
|
|
|
50
50
|
* archives that were never meant to be served.
|
|
51
51
|
*/
|
|
52
52
|
export declare function sizeAdvice(shape: UploadShape, markers?: FolderMarkers): string | null;
|
|
53
|
+
/**
|
|
54
|
+
* Which of `sizeAdvice`'s answers applies, as a word: the CLI uses it to pick
|
|
55
|
+
* which files to name (it has the names; the server and the report do not).
|
|
56
|
+
*/
|
|
57
|
+
export declare function sizeCause(shape: UploadShape, markers?: FolderMarkers): "project_root" | "source_map" | "media" | "archive" | "image" | null;
|
package/package.json
CHANGED