flypod 0.16.1 → 0.18.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.
@@ -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,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>;
@@ -15,6 +15,8 @@ interface RequestInit {
15
15
  json?: unknown;
16
16
  zip?: Uint8Array;
17
17
  query?: Record<string, string | undefined>;
18
+ /** Headers for this one request, on top of the client's own. */
19
+ headers?: Record<string, string>;
18
20
  }
19
21
  export interface FlypodClient {
20
22
  readonly baseUrl: string;
@@ -33,7 +35,10 @@ export interface FlypodClient {
33
35
  manage_token: string;
34
36
  }>): Promise<Response>;
35
37
  getSite(siteId: string): Promise<Response>;
36
- createSite(zip: Uint8Array): Promise<Response>;
38
+ /** `relink`: this folder already deployed to another site (`x-flypod-relink`). */
39
+ createSite(zip: Uint8Array, opts?: {
40
+ relink?: boolean;
41
+ }): Promise<Response>;
37
42
  redeploy(siteId: string, zip: Uint8Array): Promise<Response>;
38
43
  rollback(siteId: string, versionId: string): Promise<Response>;
39
44
  setTimeline(siteId: string, enabled: boolean): Promise<Response>;
@@ -79,7 +84,11 @@ export declare function resolveCredentials(env: NodeJS.ProcessEnv, session: CliS
79
84
  export declare function buildClient(token: string | undefined, baseUrl: string, fetchImpl: FetchLike,
80
85
  /** Deploy attribution. Defaults to `library`: the only callers that build a
81
86
  * client without saying so are library embedders (see src/cli.ts). */
82
- source?: DeploySource): FlypodClient;
87
+ source?: DeploySource,
88
+ /** Sent on every request. Only `createClient` passes any (install id and
89
+ * CLI version); a library caller gets none, so `deploySite` stays free of
90
+ * anything that identifies the machine it runs on. */
91
+ extraHeaders?: Record<string, string>): FlypodClient;
83
92
  /**
84
93
  * Build a client with credentials resolved once (a saved session is loaded
85
94
  * from disk, so this is async). `opts.fetch`/`opts.env` are the same
@@ -88,7 +97,10 @@ source?: DeploySource): FlypodClient;
88
97
  *
89
98
  * The deploy source is resolved here too (see ./source.ts) so that every
90
99
  * command routed through the CLI — not just `deploy` — reports the surface it
91
- * came from without each one having to remember.
100
+ * came from without each one having to remember. So are the install id and
101
+ * CLI version (see ./install-id.ts), for the same reason: the server can only
102
+ * tell one person's tenth deploy from ten people's first if every request
103
+ * says which install sent it.
92
104
  */
93
105
  export declare function createClient(opts: {
94
106
  env?: NodeJS.ProcessEnv;
@@ -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;
@@ -1,5 +1,12 @@
1
+ import type { CLI_ERROR_CODES, NO_SITE_REASONS, SENT_CREDENTIALS, SERVER_ERROR_ORIGINS } from "../cli-error-codes";
1
2
  import type { CommandIO } from "./commands";
2
- export type ErrorCode = "usage" | "unknown_command" | "unknown_flag" | "no_build_dir" | "no_files" | "no_site" | "no_token" | "not_signed_in" | "unauthorized" | "token_rejected" | "not_found" | "no_such_version" | "site_gone" | "already_claimed" | "invalid_upload" | "too_large" | "blocked" | "challenge_required" | "rate_limited" | "server_error" | "bad_request" | "network" | "interactive_login_required" | "authorization_pending" | "login_denied" | "login_expired" | "login_timeout" | "unexpected";
3
+ export { CLI_ERROR_CODES, NO_SITE_REASONS } from "../cli-error-codes";
4
+ /**
5
+ * Every code a CLI failure can carry, grouped in `CLI_ERROR_CODES` by where it
6
+ * comes from. The list is a value in its own module so the control plane can
7
+ * validate failure reports against it without bundling the CLI.
8
+ */
9
+ export type ErrorCode = (typeof CLI_ERROR_CODES)[number];
3
10
  export interface CliError {
4
11
  code: ErrorCode;
5
12
  /** Human-readable reason. Free text; agents branch on `code` instead. */
@@ -10,6 +17,12 @@ export interface CliError {
10
17
  status?: number;
11
18
  /** Extra machine-readable fields merged into the JSON envelope. */
12
19
  extra?: Record<string, unknown>;
20
+ /**
21
+ * Fields for the failure report only (./telemetry.ts), never printed: the
22
+ * upload's shape and folder markers, in counts and fixed words. Kept apart
23
+ * from `extra` so the `--json` envelope does not grow a field per metric.
24
+ */
25
+ telemetry?: Record<string, unknown>;
13
26
  }
14
27
  export declare function exitCodeFor(code: ErrorCode): number;
15
28
  /** The wire shape, exactly as it is written to stdout under `--json`. */
@@ -45,7 +58,36 @@ export declare function readServerMessage(res: Response): Promise<{
45
58
  message: string;
46
59
  code?: string;
47
60
  json?: boolean;
61
+ /** The server's own next step, when its answer carried one. */
62
+ fix?: string;
63
+ /** Which limit a 413 hit (`files`, `total_bytes`, …), when the server said. */
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;
48
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];
49
91
  export interface ClassifyContext {
50
92
  /** `flypod update`, `flypod comments post`, … — for the human prefix. */
51
93
  verb: string;
@@ -58,8 +100,27 @@ export interface ClassifyContext {
58
100
  * Turn a non-2xx response into a `CliError` with a stable code and a fix.
59
101
  * The server's own `code` wins when it sends one (e.g. `token_rejected`);
60
102
  * otherwise the status decides.
103
+ *
104
+ * The server's `fix` wins over the CLI's, for every code. The CLI's fixes are
105
+ * written per status and can only guess (a 413 used to say "shrink the build"
106
+ * whether the build was a project root, a folder of videos or 2 MB of source
107
+ * maps); the server has the upload in hand and can say which. It also lets a
108
+ * better answer reach every installed CLI without waiting for an upgrade.
61
109
  */
62
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.";
116
+ /** The limits a `too_large` can name, in the CLI's precheck and in a report. */
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;
63
124
  /**
64
125
  * No folder to deploy. `resolveDeployDir` throws one long sentence (it is a
65
126
  * library function and its message has to stand alone); here it is split into
@@ -70,6 +131,49 @@ export declare function noBuildDir(message: string): CliError;
70
131
  export declare function networkError(e: unknown, baseUrl?: string): CliError;
71
132
  /** The canonical "nothing is linked here" failure, shared by every verb that targets a site. */
72
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
+ /**
138
+ * `no_site` for the version verbs (`update`, `versions`, `rollback`), told
139
+ * apart by what this machine remembers about the folder. It was one sentence
140
+ * for all of them ("No flypod site is linked to this folder"), so the person
141
+ * whose temporary site had expired on day 14 was told the folder had never
142
+ * been deployed, and an agent could not tell "make the site" from "it is
143
+ * gone" from "you are one folder off". The code stays `no_site`; `reason`
144
+ * says which (NO_SITE_REASONS), and `fix` is the one command for it.
145
+ */
146
+ export declare function noSite(ctx: {
147
+ /** `update`, `versions`, `rollback`. */
148
+ verb: string;
149
+ gone?: {
150
+ site_id: string;
151
+ url: string;
152
+ reason: "expired" | "gone";
153
+ at: number;
154
+ } | null;
155
+ nearby?: {
156
+ dir: string;
157
+ site_id: string;
158
+ } | null;
159
+ signedIn?: boolean;
160
+ }): CliError;
161
+ /**
162
+ * `unauthorized` on a site-scoped request, with the fix that matches the
163
+ * credential this machine sent. The server answers 401 alike for a site
164
+ * that no longer exists, a site kept by an account, and a wrong token (a
165
+ * site id is public; which of those it is, is not), so the CLI says what it
166
+ * knows: what it sent. 15 people in a week got "Run `flypod login`, or pass
167
+ * --token <manage_token>", which fit none of them.
168
+ */
169
+ export declare function unauthorizedFor(ctx: {
170
+ siteId: string;
171
+ /** What authorized the request: `--token`, this folder's manage token, an account, or nothing. */
172
+ sent: SentCredential;
173
+ /** Whether this machine has any record of the site. */
174
+ known: boolean;
175
+ status?: number;
176
+ }): CliError;
73
177
  export declare const NOT_SIGNED_IN: CliError;
74
178
  /** Message for `main().catch` and any other last-resort handler. */
75
179
  export declare function unexpectedError(e: unknown): CliError;
@@ -0,0 +1,42 @@
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
+ /**
8
+ * True when the user asked not to be counted. `DO_NOT_TRACK` counts when set
9
+ * to anything but an explicit "no" (`""`, `0`, `false`), because the
10
+ * convention is "set it to turn tracking off" and people write `=1`, `=yes`
11
+ * and `=true` alike.
12
+ */
13
+ export declare function telemetryOptedOut(env: NodeJS.ProcessEnv): boolean;
14
+ export declare function installFilePath(env?: NodeJS.ProcessEnv): string;
15
+ export interface InstallId {
16
+ id: string;
17
+ /** True only in the process that created the id: the server's "new install" signal. */
18
+ isNew: boolean;
19
+ }
20
+ /**
21
+ * This machine's install id, created on first use. Null when opted out, or
22
+ * when the config directory cannot be written: no id is better than a fresh
23
+ * one every run, which would count one person as a new install each time.
24
+ * Never throws: nothing about counting may fail a deploy.
25
+ */
26
+ export declare function installId(env?: NodeJS.ProcessEnv): Promise<InstallId | null>;
27
+ export declare function setCliVersion(v: string): void;
28
+ export declare function cliVersion(): string | undefined;
29
+ /**
30
+ * The headers that say which install and which CLI version is calling, and
31
+ * whether a coding agent or a CI system is running it (./agent-env.ts). The
32
+ * version is not identifying and is always sent (when known); everything else
33
+ * follows the opt-out, because "which agent does this person use" is a fact
34
+ * about them, not about the CLI.
35
+ */
36
+ export declare function identityHeaders(env: NodeJS.ProcessEnv): Promise<Record<string, string>>;
37
+ /**
38
+ * The one line a person sees the first time an id is made, so being counted
39
+ * is never a surprise. One line because the default output is short, and it
40
+ * names the switch rather than a page to read.
41
+ */
42
+ export declare const FIRST_RUN_NOTICE = "flypod counts deploys with a random id. DO_NOT_TRACK=1 stops it.";
@@ -1,7 +1,51 @@
1
1
  import type { UploadLimits } from "../ingest-error";
2
2
  import type { CliError } from "./errors";
3
+ /**
4
+ * What a failure report says about an upload: its shape by kind of byte, what
5
+ * its top level looks like, and the archive size. Counts and fixed words
6
+ * only; see ../upload-shape.ts for why no names.
7
+ */
8
+ export declare function uploadReport(files: Record<string, Uint8Array>, skippedCount?: number): Record<string, unknown>;
3
9
  /**
4
10
  * `too_large` with the limit and the biggest files named, or null when the
5
11
  * build fits or the limits are unknown (`uploadLimitsFor` returned null).
12
+ *
13
+ * The fix is `sizeAdvice` when the upload's shape says something specific
14
+ * (a project root instead of its build folder, source maps, video): "remove
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).
32
+ */
33
+ export declare function ignoreFilePath(dir: string, cwd: string): Promise<string | undefined>;
34
+ /**
35
+ * Sharpen a `no_build_dir` / `no_files` failure with what the current folder
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.
42
+ *
43
+ * `deployed` is the folder that turned out empty (for `no_files`), so the fix
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.
6
47
  */
7
- export declare function checkUploadSize(files: Record<string, Uint8Array>, limits: UploadLimits | null): CliError | null;
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): Promise<string>;
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
- /** Forget the link for a directory. Returns whether anything was removed. */
57
- export declare function forgetDir(dir: string, env?: NodeJS.ProcessEnv): Promise<boolean>;
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
@@ -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 ../deploy-source.ts). Deliberately
93
- * project-scoped: `--global` installs are machine-wide and would label a
94
- * human's own deploys as agent deploys forever, so they're left to the
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;
@@ -126,10 +140,17 @@ export interface InstallSkillArgs {
126
140
  dryRun?: boolean;
127
141
  /** Project root. Defaults to cwd; tests inject. */
128
142
  cwd?: string;
143
+ /**
144
+ * One line of JSON on stdout and nothing on stderr, like every other verb.
145
+ * `install skill` used to accept `--json` and ignore it, printing
146
+ * tab-separated rows and prose instead, so an agent that installed the
147
+ * skill had nothing to parse.
148
+ */
149
+ json?: boolean;
129
150
  /**
130
151
  * A picker for interactive use. Given the plan, returns the chosen target
131
152
  * ids, or null if the user cancelled. Omitted in non-interactive contexts.
132
153
  */
133
154
  picker?: (plan: PlanEntry[]) => Promise<string[] | null>;
134
155
  }
135
- export declare function installSkill(args: InstallSkillArgs, io: CommandIO): Promise<number>;
156
+ export declare function installSkill(args: InstallSkillArgs, callerIo: CommandIO): Promise<number>;
@@ -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): Promise<DeploySource>;
7
+ export declare function resolveCliSource(env: NodeJS.ProcessEnv, cwd: string, opts?: {
8
+ stdoutIsTTY?: boolean;
9
+ }): Promise<DeploySource>;
@@ -0,0 +1,38 @@
1
+ import type { CliError } from "./errors";
2
+ type FetchLike = typeof fetch;
3
+ export declare const REPORT_TIMEOUT_MS = 1500;
4
+ export declare const TELEMETRY_PATH = "/telemetry/cli";
5
+ /** Turn reports on for this process. Called once by bin/deploy.ts; tests inject. */
6
+ export declare function startFailureReports(opts: {
7
+ verb: string;
8
+ /** `--help` anywhere on the line: nothing this run does is a failure worth counting. */
9
+ help?: boolean;
10
+ env?: NodeJS.ProcessEnv;
11
+ fetch?: FetchLike;
12
+ cwd?: string;
13
+ stdoutIsTTY?: boolean;
14
+ }): void;
15
+ /** Turn reports off again (tests). */
16
+ export declare function stopFailureReports(): void;
17
+ /**
18
+ * Queue the report for a failure that has just been shown. Returns at once;
19
+ * the request runs in the background until `flushFailureReports`.
20
+ */
21
+ export declare function reportFailure(err: CliError, args: {
22
+ json?: boolean;
23
+ }): void;
24
+ /**
25
+ * Wait for queued reports, bounded. Each one aborts itself at
26
+ * REPORT_TIMEOUT_MS; the outer timer is for a transport that ignores the
27
+ * abort signal, so exit is never held past it.
28
+ */
29
+ export declare function flushFailureReports(): Promise<void>;
30
+ /**
31
+ * The report for one failure: the code and where it happened, plus whatever
32
+ * the failure carries in `telemetry` (the upload's shape for `too_large`,
33
+ * folder markers for `no_files` / `no_build_dir`). Only strings, finite
34
+ * numbers and booleans pass, so a null in a shape never becomes a field the
35
+ * server has to reject the whole report over.
36
+ */
37
+ export declare function reportBody(err: CliError, verb: string, agent: boolean): Record<string, unknown>;
38
+ export {};
@@ -0,0 +1,28 @@
1
+ export declare const CLI_ERROR_CODES: readonly ["usage", "unknown_command", "unknown_flag", "no_build_dir", "no_files", "no_site", "no_token", "not_signed_in", "unauthorized", "token_rejected", "not_found", "no_such_version", "site_gone", "already_claimed", "invalid_upload", "too_large", "blocked", "challenge_required", "rate_limited", "server_error", "bad_request", "network", "interactive_login_required", "authorization_pending", "login_denied", "login_expired", "login_timeout", "unexpected"];
2
+ /**
3
+ * The verbs a failure report may name: `SUBCOMMANDS` in bin/deploy.ts, which
4
+ * already includes `deploy`. Copied rather than imported for the same reason
5
+ * as the codes; `test/cli-telemetry.test.ts` holds the two lists equal.
6
+ * `--help` and a deploy path are not verbs: a failed deploy reports `deploy`.
7
+ */
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"];
package/dist/src/cli.d.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  import { type DeploySource } from "./deploy-source";
2
+ export type { DeploySource } from "./deploy-source";
2
3
  /**
3
4
  * Build-output folders the common frontend frameworks emit, in priority order.
4
5
  * `public` ranks low because some tools use it for *source* assets (Vite/CRA);
@@ -6,9 +7,21 @@ import { type DeploySource } from "./deploy-source";
6
7
  */
7
8
  export declare const BUILD_DIR_CANDIDATES: string[];
8
9
  /**
9
- * Resolve the directory to deploy. An explicit path is used verbatim. Otherwise
10
- * the first candidate build folder that exists and contains an index.html wins,
11
- * so `npx flypod` (no argument) just works from a project root.
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.
12
25
  */
13
26
  export declare function resolveDeployDir(opts?: {
14
27
  cwd?: string;
package/dist/src/cli.js CHANGED
@@ -7,7 +7,7 @@ import {
7
7
  collectFiles,
8
8
  deploySite,
9
9
  resolveDeployDir
10
- } from "../cli-8h0vc7g2.js";
10
+ } from "../cli-4d5fkx95.js";
11
11
  export {
12
12
  BUILD_DIR_CANDIDATES,
13
13
  DEFAULT_IGNORES,
@@ -0,0 +1,50 @@
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
+ /**
8
+ * Which coding agent ran the CLI, as one of these words and nothing else. The
9
+ * CLI reads it from environment variables the agents themselves set
10
+ * (src/cli/agent-env.ts) and sends the word, never a variable's value.
11
+ *
12
+ * Why it exists: 85% of the week of 2026-10-26's deploys read `source: cli`
13
+ * and most of those deployers never opened the website, so whether they were
14
+ * people at a terminal or agents working for them was a guess. `source` cannot
15
+ * carry the answer, because it names *our* surface and a skill-taught agent is
16
+ * still running the CLI.
17
+ *
18
+ * `other` is a tool that announces itself through the `AI_AGENT` convention
19
+ * with a name not on this list; `none` is a run with no agent in sight.
20
+ */
21
+ export declare const CODING_AGENTS: readonly ["claude_code", "codex", "cursor", "gemini", "opencode", "other", "none"];
22
+ export type CodingAgent = (typeof CODING_AGENTS)[number];
23
+ export interface ClientMeta {
24
+ install_id?: string;
25
+ /** Only on requests from the process that created the install id. */
26
+ install_new?: true;
27
+ cli_version?: string;
28
+ /** The folder was already linked to a site when this `POST /sites` was made. */
29
+ relinked?: true;
30
+ /** The coding agent that ran the CLI (`none` for none); absent from older CLIs. */
31
+ coding_agent?: CodingAgent;
32
+ /** The CLI ran under a CI system (`CI`, `GITHUB_ACTIONS`, …); absent from older CLIs. */
33
+ ci?: boolean;
34
+ }
35
+ /**
36
+ * The valid subset of the CLI's headers. Each is checked on its own and an
37
+ * invalid one is dropped, never the request: these are measurement, and a
38
+ * deploy must not fail because a header was malformed.
39
+ *
40
+ * `install_new` without a valid `install_id` is dropped too: "this id is new"
41
+ * means nothing with no id beside it.
42
+ */
43
+ export declare function clientMeta(headers: Headers): ClientMeta;
44
+ /**
45
+ * The properties `event` gets from these headers. `relinked` belongs to
46
+ * `site_deployed` alone: it describes why a new site was made (a folder that
47
+ * already had one), and on any other event it would read as a fact about that
48
+ * event instead.
49
+ */
50
+ export declare function clientMetaProps(headers: Headers, event: string): Record<string, unknown>;