flypod 0.7.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,3 +1,4 @@
1
+ import type { DeploySource } from "../deploy-source";
1
2
  import type { CliSession } from "./session";
2
3
  type FetchLike = typeof fetch;
3
4
  /** Per-call-site credential overrides — `--token`/`--site` flags, or a
@@ -18,6 +19,8 @@ interface RequestInit {
18
19
  export interface FlypodClient {
19
20
  readonly baseUrl: string;
20
21
  readonly token: string | undefined;
22
+ /** Surface reported to the server on every request (`x-flypod-source`). */
23
+ readonly source: DeploySource;
21
24
  /** Low-level escape hatch: `path` is resolved against `baseUrl`; the auth
22
25
  * header is added when a token resolved. */
23
26
  request(method: string, path: string, init?: RequestInit): Promise<Response>;
@@ -72,16 +75,25 @@ export declare function resolveCredentials(env: NodeJS.ProcessEnv, session: CliS
72
75
  * that a *published library call* never has a side channel to a session
73
76
  * file or ambient env vars it didn't ask for.
74
77
  */
75
- export declare function buildClient(token: string | undefined, baseUrl: string, fetchImpl: FetchLike): FlypodClient;
78
+ export declare function buildClient(token: string | undefined, baseUrl: string, fetchImpl: FetchLike,
79
+ /** Deploy attribution. Defaults to `library`: the only callers that build a
80
+ * client without saying so are library embedders (see src/cli.ts). */
81
+ source?: DeploySource): FlypodClient;
76
82
  /**
77
83
  * Build a client with credentials resolved once (a saved session is loaded
78
84
  * from disk, so this is async). `opts.fetch`/`opts.env` are the same
79
85
  * injection seam `CommandIO` already offers commands, so tests keep working
80
86
  * hermetically end to end.
87
+ *
88
+ * The deploy source is resolved here too (see ./source.ts) so that every
89
+ * command routed through the CLI — not just `deploy` — reports the surface it
90
+ * came from without each one having to remember.
81
91
  */
82
92
  export declare function createClient(opts: {
83
93
  env?: NodeJS.ProcessEnv;
84
94
  fetch?: FetchLike;
85
95
  overrides?: ClientOverrides;
96
+ /** Project root used for skill detection. Defaults to cwd; tests inject. */
97
+ cwd?: string;
86
98
  }): Promise<FlypodClient>;
87
99
  export {};
@@ -0,0 +1,68 @@
1
+ type FetchLike = typeof fetch;
2
+ export interface CommandIO {
3
+ /** Write a line to stdout (the scriptable surface). */
4
+ out(line: string): void;
5
+ /** Write a line to stderr (humans and errors). */
6
+ err(line: string): void;
7
+ /** Network call. Default is the global fetch; tests inject. */
8
+ fetch?: FetchLike;
9
+ /** Override the process env (tests). */
10
+ env?: NodeJS.ProcessEnv;
11
+ /** Working directory used for folder->site lookup + deploy-dir resolution. */
12
+ cwd?: string;
13
+ /** Open a URL in the default browser. Tests inject a no-op. */
14
+ openUrl?: (url: string) => Promise<void>;
15
+ }
16
+ export declare function login(args: {
17
+ token?: string;
18
+ help?: boolean;
19
+ }, io: CommandIO): Promise<number>;
20
+ export declare function logout(_args: Record<string, never>, io: CommandIO): Promise<number>;
21
+ export declare function list(_args: Record<string, never>, io: CommandIO): Promise<number>;
22
+ export declare function claim(args: {
23
+ site_id?: string;
24
+ token?: string;
25
+ }, io: CommandIO): Promise<number>;
26
+ export declare function update(args: {
27
+ path?: string;
28
+ site?: string;
29
+ token?: string;
30
+ json?: boolean;
31
+ quiet?: boolean;
32
+ help?: boolean;
33
+ }, io: CommandIO): Promise<number>;
34
+ export declare function versions(args: {
35
+ site?: string;
36
+ token?: string;
37
+ json?: boolean;
38
+ help?: boolean;
39
+ }, io: CommandIO): Promise<number>;
40
+ export declare function rollback(args: {
41
+ version?: string;
42
+ site?: string;
43
+ token?: string;
44
+ json?: boolean;
45
+ help?: boolean;
46
+ }, io: CommandIO): Promise<number>;
47
+ /**
48
+ * Reveal a site's manage token on demand.
49
+ *
50
+ * Deploy output redacts the token, because the moment it is printed it is in a
51
+ * scrollback buffer, a screen recording, or a pasted support thread — and the
52
+ * server only ever stored its hash, so it cannot be rotated, only outlived.
53
+ * Redacting costs nothing: the token is already saved for the folder, so the
54
+ * commands that need it read it from there.
55
+ *
56
+ * This is the escape hatch for the one case that genuinely needs the plaintext
57
+ * — acting on the site from somewhere that doesn't remember it. The token goes
58
+ * to stdout so it pipes; everything else goes to stderr.
59
+ */
60
+ export declare function token(args: {
61
+ site?: string;
62
+ help?: boolean;
63
+ }, io: CommandIO): Promise<number>;
64
+ export declare function forget(args: {
65
+ site?: string;
66
+ help?: boolean;
67
+ }, io: CommandIO): Promise<number>;
68
+ export {};
@@ -0,0 +1,35 @@
1
+ export { projectsFilePath } from "./paths";
2
+ /** One linked project — keyed in the file by its absolute directory. */
3
+ export interface ProjectRecord {
4
+ /** The site this folder deploys to. */
5
+ site_id: string;
6
+ /** The live URL (for display + convenience). */
7
+ url: string;
8
+ /** Host the site lives on, so commands hit the right server. */
9
+ base_url: string;
10
+ /** Per-site secret for anonymous sites. Omitted for account-owned sites. */
11
+ manage_token?: string;
12
+ /** Epoch ms the site expires (anonymous), or null when owned/permanent. */
13
+ expires_at: number | null;
14
+ /** Epoch ms of the last command that touched this entry (drives LRU). */
15
+ last_used: number;
16
+ /** Last version we know is live here — lets `update` detect a no-op. */
17
+ version_id?: string;
18
+ }
19
+ /** Hard cap on remembered projects — keeps projects.json bounded forever. */
20
+ export declare const MAX_PROJECTS = 64;
21
+ /**
22
+ * Load the registry, pruning expired entries. A missing or corrupt file is
23
+ * treated as an empty registry — this never throws.
24
+ */
25
+ export declare function loadProjects(env?: NodeJS.ProcessEnv): Promise<Record<string, ProjectRecord>>;
26
+ /** 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>;
28
+ /** Link (or repoint) a directory to a site. */
29
+ export declare function linkProject(dir: string, rec: ProjectRecord, env?: NodeJS.ProcessEnv): Promise<void>;
30
+ /** The site linked to a directory, or null. */
31
+ export declare function projectForDir(dir: string, env?: NodeJS.ProcessEnv): Promise<ProjectRecord | null>;
32
+ /** Forget the link for a directory. Returns whether anything was removed. */
33
+ export declare function forgetDir(dir: string, env?: NodeJS.ProcessEnv): Promise<boolean>;
34
+ /** Forget every link pointing at a site id. Returns how many were removed. */
35
+ export declare function forgetSite(site_id: string, env?: NodeJS.ProcessEnv): Promise<number>;
@@ -0,0 +1,135 @@
1
+ import type { CommandIO } from "./commands";
2
+ /** Skill name. Doubles as the skill directory name in every target. */
3
+ export declare const SKILL_NAME = "flypod";
4
+ /**
5
+ * The skill's frontmatter description — the single highest-leverage string in
6
+ * the CLI, because it is the *retrieval* surface: what an agent matches against
7
+ * when deciding, mid-turn, whether flypod is the right move.
8
+ *
9
+ * It is a context pointer, so it is priced per turn whether or not it fires,
10
+ * and it earns harder pruning than the body. Two rules govern it:
11
+ *
12
+ * - **One trigger per branch.** Synonyms that rename a single branch are one
13
+ * branch written twice. "deploy, publish, ship, host, preview, share, send
14
+ * a link" is *one* branch — the user asked — and costs seven times its
15
+ * weight. Four branches genuinely differ, because a different run reaches
16
+ * the skill through each: the user asks; a build finished and someone else
17
+ * must see it; Markdown should become a site rather than a file (a distinct
18
+ * code path, and the capability agents are least likely to guess); and a
19
+ * screenshot or dev server will not do because the recipient must open it
20
+ * themselves. That last one does the most work — it names the default
21
+ * behaviour flypod displaces, which is the moment the model is actually
22
+ * reasoning through.
23
+ * - **Cut identity the body carries.** The pointer decides *when* to reach
24
+ * the skill; what flypod is belongs in the skill.
25
+ *
26
+ * The trailing boundary is the exception that earns its tokens: a skill that
27
+ * fires on an app with server routes produces a broken deploy, and one bad
28
+ * selection costs more than ten missed ones.
29
+ *
30
+ * Keep it free of `: ` and quote characters: it is rendered into YAML
31
+ * frontmatter. `yamlScalar` quotes it defensively, but plain text keeps the
32
+ * generated files readable and diff-friendly.
33
+ */
34
+ export declare const SKILL_DESCRIPTION: string;
35
+ /**
36
+ * One reference doc in the skill payload. Every entry is listed in the entry
37
+ * file's table, so adding one here without adding it to `REFERENCES` would
38
+ * strand it — unreachable content the agent never learns exists.
39
+ */
40
+ export interface ReferenceDoc {
41
+ /** Path relative to the skill directory. */
42
+ file: string;
43
+ /** Column 2 of the entry file's table: when to open this. */
44
+ when: string;
45
+ body(): string;
46
+ }
47
+ /**
48
+ * The reference set, in the order they appear in the entry file's table.
49
+ * Ordered by how often a deploy turns into each follow-up: shipping a change is
50
+ * near-universal, Markdown publishing is the most-missed capability, comments
51
+ * are deliberate, troubleshooting is on failure.
52
+ */
53
+ export declare const REFERENCES: ReferenceDoc[];
54
+ /** The entry `SKILL.md`: required frontmatter plus the always-loaded body. */
55
+ export declare function skillEntryFile(): string;
56
+ /**
57
+ * The complete skill directory: entry file plus every reference doc, keyed by
58
+ * path relative to the skill directory. This is the whole payload, and it is
59
+ * identical for every target — SKILL.md is a shared standard now.
60
+ */
61
+ export declare function skillFiles(): Record<string, string>;
62
+ export interface Target {
63
+ id: string;
64
+ /** Human label shown in the picker and reports. */
65
+ label: string;
66
+ /** One-line "what this is" for the picker. */
67
+ detail: string;
68
+ /** The skill directory within the project root. */
69
+ projectDir(root: string): string;
70
+ /** The skill directory under the user's home, for `--global`. */
71
+ globalDir(env: NodeJS.ProcessEnv): string;
72
+ }
73
+ /**
74
+ * Both targets get the same files. They are separate entries only because they
75
+ * are separate directories on disk: Claude Code reads `.claude/skills/`, and
76
+ * everything else has converged on `.agents/skills/`. If Claude Code ever scans
77
+ * `.agents/skills/` too, this collapses to one.
78
+ */
79
+ export declare const TARGETS: Target[];
80
+ export declare function targetById(id: string): Target | undefined;
81
+ /**
82
+ * Legacy flypod instruction files still present in this project. A dedicated
83
+ * file counts on existence; a shared file counts only when it still carries the
84
+ * flypod block marker, so an AGENTS.md that merely mentions flypod is ignored.
85
+ */
86
+ export declare function legacyArtifacts(root: string): Promise<string[]>;
87
+ /**
88
+ * Is this project one where `flypod install skill` has been run? Answered from
89
+ * the only evidence that exists on the user's machine: the skill files the
90
+ * command itself writes.
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.
96
+ */
97
+ export declare function skillInstalledIn(root: string): Promise<boolean>;
98
+ export type WriteStatus = "created" | "updated" | "unchanged";
99
+ export interface WriteResult {
100
+ target: Target;
101
+ /** Absolute path of the file written. */
102
+ path: string;
103
+ status: WriteStatus;
104
+ }
105
+ export interface PlanEntry {
106
+ target: Target;
107
+ /** The skill directory this target would write. */
108
+ dir: string;
109
+ }
110
+ /**
111
+ * Resolve where each target writes. Both targets are always offered: the cost
112
+ * of an unused skill directory is a few KB, and the cost of guessing wrong is
113
+ * an agent that never learns flypod exists.
114
+ */
115
+ export declare function buildPlan(root: string, env: NodeJS.ProcessEnv, global: boolean): Promise<PlanEntry[]>;
116
+ export interface InstallSkillArgs {
117
+ /** Explicit target ids from flags (e.g. --claude --agents). Empty = all. */
118
+ targets?: string[];
119
+ /** Write every target without prompting, even in a TTY. */
120
+ all?: boolean;
121
+ /** Write to home-dir locations instead of the project. */
122
+ global?: boolean;
123
+ /** Just print where things would go; write nothing. */
124
+ list?: boolean;
125
+ /** Show the planned files (and exit) without writing. */
126
+ dryRun?: boolean;
127
+ /** Project root. Defaults to cwd; tests inject. */
128
+ cwd?: string;
129
+ /**
130
+ * A picker for interactive use. Given the plan, returns the chosen target
131
+ * ids, or null if the user cancelled. Omitted in non-interactive contexts.
132
+ */
133
+ picker?: (plan: PlanEntry[]) => Promise<string[] | null>;
134
+ }
135
+ export declare function installSkill(args: InstallSkillArgs, io: CommandIO): Promise<number>;
@@ -0,0 +1,7 @@
1
+ import { type DeploySource } from "../deploy-source";
2
+ /**
3
+ * Resolve the source for a CLI-originated request. Falls back to `cli`, which
4
+ * is the truth for a plain terminal invocation. Never throws: an unreadable
5
+ * project must not be able to fail a deploy.
6
+ */
7
+ export declare function resolveCliSource(env: NodeJS.ProcessEnv, cwd: string): Promise<DeploySource>;
package/dist/src/cli.d.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import type { DeploySource } from "./deploy-source";
1
2
  /**
2
3
  * Build-output folders the common frontend frameworks emit, in priority order.
3
4
  * `public` ranks low because some tools use it for *source* assets (Vite/CRA);
@@ -30,6 +31,17 @@ export interface DeployResult {
30
31
  manage_token: string;
31
32
  /** Set when the deploy was authenticated via Bearer apiKey or cookie session. */
32
33
  owner_account_id?: string;
34
+ /** Problems the deploy pipeline fixed on the caller's behalf, e.g. `spa-fallback`. */
35
+ healed?: string[];
36
+ /**
37
+ * Problems it could *not* fix, each with a `fix_recipe` naming the change to
38
+ * make. A deploy can succeed and still be broken for visitors, so this is the
39
+ * only signal an agent has that the URL it is about to hand over is wrong.
40
+ */
41
+ warnings?: Array<{
42
+ code: string;
43
+ fix_recipe: string;
44
+ }>;
33
45
  next_actions: unknown[];
34
46
  }
35
47
  export interface DeployOptions {
@@ -40,6 +52,12 @@ export interface DeployOptions {
40
52
  handle?: (request: Request) => Promise<Response>;
41
53
  /** When set, sent as `Authorization: Bearer <apiKey>` so the deploy is attributed. */
42
54
  apiKey?: string;
55
+ /**
56
+ * Surface reported to the server as `x-flypod-source`. Defaults to
57
+ * `library`, which is the truth for a direct call to this function; the
58
+ * `flypod` binary passes its own resolved source (`cli` or `skill`).
59
+ */
60
+ source?: DeploySource;
43
61
  }
44
62
  /**
45
63
  * Zip a files map and POST it to the deploy API; returns the parsed result.
package/dist/src/cli.js CHANGED
@@ -3,7 +3,7 @@ import {
3
3
  collectDist,
4
4
  deploySite,
5
5
  resolveDeployDir
6
- } from "../cli-j9rxpfdv.js";
6
+ } from "../cli-g2wb2hxm.js";
7
7
  export {
8
8
  resolveDeployDir,
9
9
  deploySite,
@@ -0,0 +1,20 @@
1
+ /** Request header carrying the deploy surface. */
2
+ export declare const SOURCE_HEADER = "x-flypod-source";
3
+ /**
4
+ * Request header carrying the caller's PostHog device id. Only our own
5
+ * first-party landing page sends it (same-origin `POST /sites`), and it is the
6
+ * one thing that lets a browser deploy be joined to the pageview that caused
7
+ * it. It is a device id we minted, not PII — no IP, no user agent.
8
+ */
9
+ export declare const ANON_ID_HEADER = "x-flypod-anon-id";
10
+ export declare const DEPLOY_SOURCES: readonly ["cli", "browser", "library", "skill", "unknown"];
11
+ export type DeploySource = (typeof DEPLOY_SOURCES)[number];
12
+ /** Validate a client-supplied source header; anything unrecognized is `unknown`. */
13
+ export declare function coerceSource(value: string | null | undefined): DeploySource;
14
+ /**
15
+ * Validate a client-supplied anon id. PostHog device ids are UUID-shaped, so a
16
+ * conservative charset + length cap is enough to keep anything else (a stray
17
+ * cookie, an injected string) out of the property. Returns undefined when the
18
+ * header is absent or implausible, so the caller can simply omit the property.
19
+ */
20
+ export declare function coerceAnonId(value: string | null | undefined): string | undefined;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "flypod",
3
- "version": "0.7.0",
3
+ "version": "0.8.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",
@@ -22,11 +22,7 @@
22
22
  "README.md",
23
23
  "LICENSE"
24
24
  ],
25
- "repository": {
26
- "type": "git",
27
- "url": "git+https://github.com/sdserranog/flypod.git",
28
- "directory": "packages/flypod"
29
- },
25
+ "homepage": "https://flypod.dev",
30
26
  "keywords": [
31
27
  "deploy",
32
28
  "agent",
@@ -57,10 +53,10 @@
57
53
  "@types/bun": "latest",
58
54
  "better-auth": "1.6.14",
59
55
  "drizzle-orm": "^0.45.2",
60
- "hono": "^4.12.25",
56
+ "hono": "^4.12.34",
61
57
  "marked": "^18.0.5",
62
58
  "playwright": "^1.60.0",
63
59
  "typescript": "^6.0.3",
64
- "wrangler": "^4.0.0"
60
+ "wrangler": "^4.36.0"
65
61
  }
66
62
  }