frontpage-host 0.1.7 → 0.1.9

package/dist/media/upload.js

@@ -0,0 +1,140 @@
+/**
+ * Shared local-file upload used by `frontpage media upload` and `prompt --attach`.
+ */
+import { randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+import { put } from "@vercel/blob/client";
+import { apiBase, CliHttpError, EXIT_AUTH, EXIT_UNEXPECTED, EXIT_USAGE, getBearerAuthHeader, httpErrorFromV1, v1PostMultipart, } from "../http/client.js";
+import { contentTypeForExt, sitePathFromKey } from "./limits.js";
+import { selectMediaTransport } from "./select-transport.js";
+async function requestClientToken(args) {
+    const auth = await getBearerAuthHeader();
+    const url = `${apiBase()}/api/v1/sites/${encodeURIComponent(args.slug)}/media/client`;
+    let res;
+    try {
+        res = await fetch(url, {
+            method: "POST",
+            headers: {
+                ...auth,
+                Accept: "application/json",
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+                type: "blob.generate-client-token",
+                payload: {
+                    pathname: args.pathname,
+                    clientPayload: JSON.stringify({ declaredSize: args.declaredSize }),
+                    multipart: args.multipart,
+                },
+            }),
+        });
+    }
+    catch (err) {
+        throw new CliHttpError(`Network error: ${err instanceof Error ? err.message : String(err)}`, EXIT_UNEXPECTED, 0);
+    }
+    const text = await res.text();
+    let parsed = {};
+    try {
+        parsed = text ? JSON.parse(text) : {};
+    }
+    catch {
+        parsed = {};
+    }
+    if (!res.ok) {
+        const msg = typeof parsed.error === "string"
+            ? parsed.error
+            : typeof parsed.error === "object" && parsed.error?.message
+                ? parsed.error.message
+                : `Upload authorization failed (${res.status})`;
+        // Auth / rate-limit use v1 envelopes; policy denials use { error: string }.
+        if (typeof parsed.error === "object" && parsed.error) {
+            throw httpErrorFromV1(res.status, parsed, msg);
+        }
+        if (res.status === 401 || res.status === 403) {
+            throw new CliHttpError(msg, EXIT_AUTH, res.status);
+        }
+        if (res.status === 402 || res.status === 413 || res.status === 429 || res.status === 400) {
+            throw new CliHttpError(msg, EXIT_USAGE, res.status);
+        }
+        throw new CliHttpError(msg, EXIT_UNEXPECTED, res.status);
+    }
+    if (typeof parsed.clientToken !== "string" || !parsed.clientToken) {
+        throw new CliHttpError("Upload authorization failed (no client token).", EXIT_UNEXPECTED, res.status);
+    }
+    return parsed.clientToken;
+}
+async function uploadViaClient(args) {
+    const pathname = `uploads/${args.slug}/${randomUUID()}.${args.ext}`;
+    const multipart = args.bytes.length > 8 * 1024 * 1024;
+    const clientToken = await requestClientToken({
+        slug: args.slug,
+        pathname,
+        declaredSize: args.bytes.length,
+        multipart,
+    });
+    try {
+        const blob = await put(pathname, args.bytes, {
+            access: "public",
+            token: clientToken,
+            contentType: args.contentType,
+            multipart,
+        });
+        const key = blob.pathname.replace(/^\//, "");
+        return {
+            kind: args.kind,
+            url: blob.url,
+            key,
+            sitePath: sitePathFromKey(key),
+            filename: args.filename,
+            sizeBytes: args.bytes.length,
+            contentType: args.contentType || contentTypeForExt(args.ext),
+            transport: "client",
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new CliHttpError(`Upload failed: ${msg}`, EXIT_UNEXPECTED, 500);
+    }
+}
+async function uploadViaProxy(args) {
+    const form = new FormData();
+    form.append("file", new Blob([Uint8Array.from(args.bytes)]), args.filename);
+    const data = await v1PostMultipart(`/api/v1/sites/${encodeURIComponent(args.slug)}/media`, form);
+    const key = data.key?.replace(/^\//, "");
+    return {
+        kind: data.kind,
+        url: data.url,
+        key,
+        sitePath: data.sitePath ?? (key ? sitePathFromKey(key) : undefined),
+        filename: data.filename ?? args.filename,
+        sizeBytes: data.sizeBytes ?? args.bytes.length,
+        contentType: data.contentType,
+        content: data.content,
+        transport: "proxy",
+    };
+}
+/** Upload a local file using the Phase E transport matrix. */
+export async function uploadLocalMedia(args) {
+    const bytes = await readFile(args.filePath);
+    const filename = basename(args.filePath);
+    const decision = selectMediaTransport({
+        filename,
+        sizeBytes: bytes.length,
+        headBytes: bytes.subarray(0, 4096),
+    });
+    if (decision.transport === "reject") {
+        throw new CliHttpError(decision.message, EXIT_USAGE, 400, "bad_request");
+    }
+    if (decision.transport === "client") {
+        return uploadViaClient({
+            slug: args.slug,
+            bytes,
+            filename,
+            ext: decision.ext,
+            contentType: decision.contentType,
+            kind: decision.kind,
+        });
+    }
+    return uploadViaProxy({ slug: args.slug, bytes, filename });
+}

package/dist/registry.js

@@ -88,10 +88,17 @@ export const COMMANDS = [
     {
         name: "push",
         summary: "Upload local allowlisted files (CAS + active-run guard)",
-        usage: "frontpage push [--site <slug>] [--message …] [--json]",
+        usage: "frontpage push [--site <slug>] [--message …] [--wait] [--json]",
         topics: ["sync"],
-        examples: ['frontpage push --message "Update hero copy"'],
-        flags: ["--site <slug>", "--message <text>"],
+        examples: [
+            'frontpage push --message "Update hero copy"',
+            'frontpage push --message "…" --wait',
+        ],
+        flags: [
+            "--site <slug>",
+            "--message <text>",
+            "--wait: after push, wait until no agent run is queued/running/deploying (same as deploy wait; not a Vercel oracle)",
+        ],
         dangers: [
             "Requires prior pull (baseCommitSha)",
             "Refused while an agent run is active (exit 3)",
@@ -197,7 +204,7 @@ export const COMMANDS = [
             "--path must start with /",
             "--attach: local file (uploads via media), /__media/… site path, or https Blob URL; repeatable",
             "--asset-url: https image URL (legacy); repeatable",
-            "Local attach uses the same caps as frontpage media upload (images/PDF/text; no CLI video yet)",
+            "Local attach uses frontpage media upload (images/PDF ≤25 MB, video ≤50 MB, SVG/text ≤4 MB proxy)",
             "stdout is bare runId (or JSON with --json)",
         ],
         seeAlso: ["runs", "deploy", "media"],
@@ -215,7 +222,10 @@ export const COMMANDS = [
             "frontpage runs retry <runId>",
             "frontpage runs get <runId>",
         ],
-        flags: ["There is no runs continue — mid-task continuation is automatic"],
+        flags: [
+            "There is no runs continue — mid-task continuation is automatic",
+            "runs wait: failed/canceled → exit 2; --json uses ok:false and includes run.error",
+        ],
         seeAlso: ["prompt", "deploy"],
     },
     {
@@ -248,6 +258,7 @@ export const COMMANDS = [
         flags: [
             "Optional build wait only — staging is https://<subdomain>.frontpage.host",
             "Does NOT promote to production; use publish only when the user asks",
+            "Fail-closed: exit 2 when the waited run (or latest, if already idle) is failed/canceled",
         ],
     },
     {
@@ -305,9 +316,20 @@ export const COMMANDS = [
     },
     {
         name: "media",
-        summary: "List or upload site media assets",
-        usage: "frontpage media list|upload <file> [--site <slug>]",
+        summary: "List or upload site media (images/PDF ≤25 MB, video ≤50 MB)",
+        usage: "frontpage media list|upload <file> [--site <slug>] [--json]",
         topics: ["content"],
+        examples: [
+            "frontpage media list",
+            "frontpage media upload ./hero.webp",
+            "frontpage media upload ./clip.mp4",
+        ],
+        flags: [
+            "Auto-selects proxy (≤4 MB) vs direct-to-Blob for large rasters/PDFs and all video",
+            "Prints sitePath (/__media/uploads/<slug>/…) for markup — never raw blob hosts in pages",
+            "SVG stays on the sanitizing proxy path (≤4 MB)",
+        ],
+        seeAlso: ["prompt", "help content", "help site-building"],
     },
     {
         name: "inbox",
@@ -422,7 +444,7 @@ export const TOPICS = {
   frontpage status               # tipDrift when remote moved since last pull
   frontpage pull                 # downloads src/, public/, content/ into cwd
   frontpage diff                 # local vs remote via git blobSha (--json → dirty + tipDrift)
-  frontpage push [--message …]   # uploads allowlisted files; CAS + active-run guard
+  frontpage push [--message …] [--wait]   # uploads allowlisted files; CAS + active-run guard
   frontpage ls [prefix]
   frontpage cat <path>
   frontpage search <pattern> [path] [--regex] [--case-sensitive] [--whole-word] [--files-only]
@@ -431,6 +453,7 @@ export const TOPICS = {
   Local state: .frontpage/state.json { slug, baseCommitSha }
   Pull BEFORE EDITING when tip may have moved (UI agent / another checkout) — check tipDrift.
   Pull before push so CAS has baseCommitSha. Do not push while the editor agent is building.
+  --wait after push blocks until no agent run is queued/running/deploying (same as deploy wait).
   The UI/canvas agent does not use this CLI; only CLI checkouts need pull.
   Pushing module markup may auto-activate modules (same as the agent).
   tokens.ts may be auto-repaired at commit if it would break the build.
@@ -473,7 +496,7 @@ export const TOPICS = {
   Modules & articles (short):
   - Forms: <form data-fp-form="slug"> with named inputs; no action/onsubmit/honeypot.
   - Articles: frontpage articles …; migrate folders via frontpage prompt (don't invent mass delete+write).
-  - Media in markup: /__media/uploads/<slug>/… from frontpage media (not raw blob URLs).
+  - Media: frontpage media upload (images/PDF ≤25 MB, video ≤50 MB). Use sitePath /__media/uploads/<slug>/… in markup (not raw blob URLs). Optional ?w= on rasters only.
 
   Full guide: https://frontpage.host/developers/site-building
   See also: frontpage help sync | content | AGENTS.md`,
@@ -482,10 +505,10 @@ export const TOPICS = {
   frontpage prompt "Use this logo" --attach ./logo.png
   frontpage prompt "…" --attach /__media/uploads/<slug>/… --asset-url https://…
   frontpage runs                 # latest + active
-  frontpage runs wait [runId]
+  frontpage runs wait [runId]    # failed/canceled → exit 2; JSON ok:false + run.error
   frontpage runs cancel <runId>
   frontpage runs retry <runId>
-  frontpage deploy wait          # optional: wait for build; NOT publish
+  frontpage deploy wait          # optional build wait; fail-closed on failed/canceled; NOT publish
   frontpage publish              # ONLY if the user asked — production promote
   frontpage unpublish --yes      # admin only; never unless asked; --yes when non-TTY
   frontpage usage
@@ -496,12 +519,13 @@ export const TOPICS = {
   frontpage modules request-setup <key> --reason "…"
   frontpage extensions
 
-  --attach uploads local files via media (images/PDF/text) or accepts /__media/… / https URLs.
+  --attach uploads via media (images/PDF/video/text) or accepts /__media/… / https URLs.
+  API errors include requestId in --json error envelopes (and stderr when not --json).
   Mid-task continuation is automatic — there is no runs continue.
-  Do not push while an agent run is active.
+  Do not file-sync while an agent run is active (see help sync for push --wait).
   Default after work: review https://<subdomain>.frontpage.host; do not publish.`,
     content: `Content
-  frontpage media list|upload <file>
+  frontpage media list|upload <file>   # images/PDF ≤25 MB, video ≤50 MB; sitePath for markup
   frontpage inbox [leads|subscribers|orders|…] [--mark-read] [--csv]
   frontpage seo get|set --path /
   frontpage articles list|content|create-section|create-article|set-draft|…
@@ -547,8 +571,9 @@ export const TOPICS = {
 
   Global --json envelope:
     { "ok": true, "command": "…", "data": {…} }
-    { "ok": false, "command": "…", "error": { "message", "code?", "httpStatus?", "exitCode" } }
-  Failures with --json still use the process exit code; envelope is on stdout.`,
+    { "ok": false, "command": "…", "error": { "message", "code?", "httpStatus?", "exitCode", "requestId?" }, "data"? }
+  Failures with --json still use the process exit code; envelope is on stdout.
+  Prefer requestId from error envelopes when filing support issues.`,
 };
 export function findCommand(name) {
     return COMMANDS.find((c) => c.name === name);

package/dist/runtime.d.ts

@@ -13,8 +13,18 @@ export type JsonErrorBody = {
     code?: string;
     httpStatus?: number;
     exitCode: number;
+    requestId?: string;
 };
 export declare function emitOk(command: string, data: unknown): void;
+/** Structured failure with optional data payload (e.g. failed run wait). */
+export declare function emitFail(command: string, args: {
+    message: string;
+    exitCode: number;
+    code?: string;
+    requestId?: string;
+    httpStatus?: number;
+    data?: unknown;
+}): number;
 export declare function emitErr(command: string, err: unknown): number;
 export declare function emitUsage(command: string, message: string, exitCode?: number): number;
 /** Progress / spinner lines — suppressed when --quiet or --json. */

package/dist/runtime.js

@@ -31,23 +31,43 @@ export function requireYesOrTty(action) {
 export function emitOk(command, data) {
     console.log(JSON.stringify({ ok: true, command, data }));
 }
+/** Structured failure with optional data payload (e.g. failed run wait). */
+export function emitFail(command, args) {
+    const body = {
+        message: args.message,
+        exitCode: args.exitCode,
+    };
+    if (args.code)
+        body.code = args.code;
+    if (args.httpStatus)
+        body.httpStatus = args.httpStatus;
+    if (args.requestId)
+        body.requestId = args.requestId;
+    if (jsonMode) {
+        const out = { ok: false, command, error: body };
+        if (args.data !== undefined)
+            out.data = args.data;
+        console.log(JSON.stringify(out));
+    }
+    else {
+        const suffix = args.requestId ? ` (requestId: ${args.requestId})` : "";
+        console.error(`${args.message}${suffix}`);
+    }
+    return args.exitCode;
+}
 export function emitErr(command, err) {
     const exitCode = exitCodeForError(err);
     const message = err instanceof Error ? err.message : String(err);
-    const body = { message, exitCode };
     if (err instanceof CliHttpError) {
-        if (err.code)
-            body.code = err.code;
-        if (err.status)
-            body.httpStatus = err.status;
+        return emitFail(command, {
+            message,
+            exitCode,
+            code: err.code,
+            httpStatus: err.status || undefined,
+            requestId: err.requestId,
+        });
     }
-    if (jsonMode) {
-        console.log(JSON.stringify({ ok: false, command, error: body }));
-    }
-    else {
-        console.error(message);
-    }
-    return exitCode;
+    return emitFail(command, { message, exitCode });
 }
 export function emitUsage(command, message, exitCode = 2) {
     if (jsonMode) {

package/llms.txt

@@ -10,12 +10,14 @@
 - Search flags: --regex --case-sensitive --whole-word --files-only --context-lines --max-results
 - Modules setup: frontpage modules request-setup <key> --reason "…" (owner status bar; CLI cannot show it)
 - Analytics ops: frontpage analytics summary|query|funnel|timeseries|compare|sql (bare analytics = dashboard)
-- Prompt attachments: frontpage prompt "…" --attach <file|/__media/…|https://…> [--asset-url https://…] (media upload for locals; images/PDF/text)
+- Media: frontpage media upload <file> (images/PDF ≤25 MB, video ≤50 MB, SVG/text ≤4 MB); use sitePath /__media/uploads/<slug>/… in markup
+- Prompt attachments: frontpage prompt "…" --attach <file|/__media/…|https://…> [--asset-url https://…] (same media caps as media upload)
+- Errors: --json error envelopes include requestId; runs wait failed/canceled → ok:false + run.error (exit 2); deploy wait fail-closed; push --wait
 - Auth: mint fp_live_ key in Frontpage UI (Developers); frontpage login KEY or FRONTPAGE_API_KEY
 - Site id: subdomain only (frontpage use <subdomain>). Not custom domains.
 - Staging: https://<subdomain>.frontpage.host — push/prompt/edit update staging; no separate staging deploy step for agents
 - Production: custom domain after frontpage publish — NEVER publish/unpublish unless the user explicitly asks
-- Sync: allowlist src/ public/ content/; platform overlay + secret-like paths rejected; pull before edit if tip may have moved (status/diff tipDrift); pull → edit → diff (blobSha) → push (CAS); no push during active agent run; UI agent does not use CLI pull; review on subdomain
+- Sync: allowlist src/ public/ content/; platform overlay + secret-like paths rejected; pull before edit if tip may have moved (status/diff tipDrift); pull → edit → diff (blobSha) → push [--wait] (CAS); no push during active agent run; UI agent does not use CLI pull; review on subdomain
 - Machine: global --json / --quiet; exit 0/2/3/4/5 (see help exit-codes)
-- deploy wait = optional build wait only; it is NOT go-live / publish
+- deploy wait = optional build wait only (fail-closed on failed/canceled); it is NOT go-live / publish
 - No runs continue, domains, billing, members, MCP, or git remotes in v1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frontpage-host",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Frontpage CLI — manage your site from the terminal",
   "type": "module",
   "bin": {
@@ -34,6 +34,9 @@
     "cli",
     "landing-page"
   ],
+  "dependencies": {
+    "@vercel/blob": "^2.4.0"
+  },
   "devDependencies": {
     "@types/node": "^22.13.10",
     "tsx": "^4.19.3",