frontpage-host 0.3.20 → 0.3.22

package/AGENTS.md

@@ -321,3 +321,7 @@ remain errors; they do not become original-file fallback successes.
 ## Native Booking
 
 Read [BOOKING.md](./BOOKING.md) before using `frontpage modules booking`. Use native settings, types/forms, members/spaces, availability, reservations and recurring blocks. Do not send new bookings through the old generic module collector. Every write requires a stable request key; updates require the current revision. Consent and private calendar-link entry stay with the human in Workspace → Connections. Ordinary owned connection management and self-hours share the workspace actions; setup requests appear in the editor status bar and overview.
+
+## Page screenshots
+
+Use `frontpage screenshots capture --path /pricing --device mobile --wait --json` to inspect a built staging page, or `frontpage screenshots get CAPTURE_ID --json` to read a result. The site context comes from `--site` or `frontpage use`. Check the returned revision, coverage and warnings. Private-site images require authenticated reads; captures expire after 30 days. Use the tool when it helps, not on every turn or edit. See [SCREENSHOTS.md](SCREENSHOTS.md) for capture modes, retries, limits and image downloads.

package/BOOKING.md

@@ -2,7 +2,7 @@
 
 Use `frontpage modules booking` to read the command list. Booking settings, forms, availability and reservations use the same service as Workspace → Bookings. The CLI uses the site's existing plan and membership rules. Admins configure settings, members/spaces and booking types. Editors manage bookings and blocks. Viewers read availability and manage their own appointment hours and authorized calendar operations through the same shared actions. Consent, private calendar-link entry and private event content require the human workspace flow.
 
-Start with `frontpage modules booking status --site SITE --json`. An admin must set the business time zone and availability, publish a booking type with assigned members or spaces, and turn online booking on. A member must already hold a Frontpage account and have joined the site. Use the existing Viewer role when inviting someone who only needs personal availability and calendar connections. Workspace Booking tabs are Calendar, Bookings, Booking types, Spaces, Connections and Settings. Choose joined site members directly in a type; there is no Booking Members screen. Each member sets My appointment hours in Settings for this site. Spaces has its own editor.
+Start with `frontpage modules booking status --site SITE --json`. Its `providerSetup.google` and `providerSetup.outlook` flags report whether new provider setup is available for this site. Unreleased options are hidden in the workspace and shared setup calls return `provider_unavailable`. Native Booking and supported iCal links do not depend on Google/Microsoft approval. Existing connection management remains available. An admin must set the business time zone and availability, publish a booking type with assigned members or spaces, and turn online booking on. A member must already hold a Frontpage account and have joined the site. Use the existing Viewer role when inviting someone who only needs personal availability and calendar connections. Workspace Booking tabs are Calendar, Bookings, Booking types, Spaces, Connections and Settings. Choose joined site members directly in a type; there is no Booking Members screen. Each member sets My appointment hours in Settings for this site. Spaces has its own editor.
 
 ## Commands
 

package/README.md

@@ -169,3 +169,7 @@ tables, scope-changing functions, custom types and unsupported syntax reject.
 Use the [analytics reference](https://frontpage.host/developers/analytics) for
 metric definitions and examples. The internal agent and MCP expose full
 page-detail report tools; this release adds no CLI command. MCP excludes SQL.
+
+## Page screenshots
+
+Use `frontpage screenshots capture --path /pricing --device mobile --wait --json` to inspect a built staging page, or `frontpage screenshots get CAPTURE_ID --json` to read a result. The site context comes from `--site` or `frontpage use`. Check the returned revision, coverage and warnings. Private-site images require authenticated reads; captures expire after 30 days. Use the tool when it helps, not on every turn or edit. See [SCREENSHOTS.md](SCREENSHOTS.md) for capture modes, retries, limits and image downloads.

package/SCREENSHOTS.md

@@ -0,0 +1,29 @@
+# Page screenshots
+
+Inspect a rendered staging page with the same capture service used by the internal agent. Capture does not edit or publish the site. Use screenshots when seeing the page helps; no capture is required every turn or after every change.
+
+```sh
+frontpage screenshots capture --site SITE --path /pricing --device mobile --wait --json
+frontpage screenshots capture --site SITE --path / --capture full_page --wait --json
+frontpage screenshots capture --site SITE --path / --capture element --selector '#contact' --wait --json
+frontpage screenshots get CAPTURE_ID --site SITE --json
+```
+
+Options: `--path` defaults to `/`; `--device` is `desktop` (1280×800) or `mobile` (390×844); `--capture` is `viewport` (default), `full_page` or `element`. Only element mode accepts/requires `--selector`, which must match exactly one element. Paths cannot contain query strings, fragments or encoded characters. Full-page capture returns ordered slices up to 24,000px; check `coverage` and `warnings`.
+
+`capture` returns an ID and queued/running/complete/failed status. `--wait` polls for up to 180 seconds. A pending result still includes its ID; use `get` to continue. A failed capture returns a nonzero exit status. `--request-key UUID` identifies one request. After an uncertain response, repeat the same input and key shown in the error; do not start another request to recover it. To make a fresh capture after a failed job, use a new key.
+
+Results describe built staging content and include its revision. They cannot show unsaved or unbuilt edits. Use `frontpage deploy wait` after a push when you want the new build, then check the returned revision. A revision change during capture fails the request rather than labeling new pixels as the old revision.
+
+Requires current site membership and normal CLI plan access (Scale, Enterprise or Internal). Each result is also bound to its requesting user; a capture ID is not permission. Private Frontpage subdomains use server-owned, site-bound access. No cookies, bypass headers, arbitrary origins or operator credentials are accepted. Up to six new captures per site per minute.
+
+New site capture images are encrypted in the existing store and delivered through authenticated API paths. In a completed result, `result.images` includes ordered `{url,width,height,top,sizeBytes}` entries. `url` is relative to `https://app.frontpage.host`; fetch it using the same API bearer credential to receive PNG bytes. Never treat the raw encrypted object as an image or publish it as a site asset. Image reads recheck permission and expiry. Results expire after 30 days; the existing reaper cleans expired files and retries failed deletions. Rotation of the server audit key makes older encrypted captures unreadable; request a new capture.
+
+```sh
+# Use an image path returned by screenshots get; keep the API key out of logs.
+curl --fail --header "Authorization: Bearer $FRONTPAGE_API_KEY" \
+  'https://app.frontpage.host/api/v1/sites/SITE/screenshots/CAPTURE_ID?image=0' \
+  --output screenshot.png
+```
+
+REST: `POST /api/v1/sites/{slug}/screenshots` with `{path,device,capture,selector?}` and optional `Idempotency-Key` UUID; `GET /api/v1/sites/{slug}/screenshots/{id}` for status/result; the same GET with `?image=N` returns PNG bytes. Images require auth even when the source page is public. MCP screenshot integration is pending; see the MCP handoff rather than assuming the command is already an MCP tool.

package/dist/bin.js

@@ -39,6 +39,7 @@ import { runSettings } from "./commands/settings.js";
 import { runEdit } from "./commands/edit.js";
 import { runFonts } from "./commands/fonts.js";
 import { runTokens } from "./commands/tokens.js";
+import { runScreenshots } from "./commands/screenshots.js";
 import { runHistory } from "./commands/history.js";
 import { runRevert } from "./commands/revert.js";
 import { runCompletion } from "./commands/completion.js";
@@ -145,6 +146,8 @@ async function main() {
             return runFonts(args);
         case "tokens":
             return runTokens(args);
+        case "screenshots":
+            return runScreenshots(args);
         case "history":
             return runHistory(args);
         case "revert":

package/dist/commands/screenshots.d.ts

@@ -0,0 +1 @@
+export declare function runScreenshots(args: string[]): Promise<number>;

package/dist/commands/screenshots.js

@@ -0,0 +1,62 @@
+import { randomUUID } from "node:crypto";
+import { resolveSlug } from "../site.js";
+import { assertNoUnknownFlags, hasFlag, takeFlagValue } from "../argv.js";
+import { CliHttpError, EXIT_OK, EXIT_USAGE, v1Get, v1Post } from "../http/client.js";
+import { emitErr, emitOk, isJson } from "../runtime.js";
+const usage = "Usage: frontpage screenshots capture [--path /] [--device desktop|mobile] [--capture viewport|full_page|element] [--selector CSS] [--request-key UUID] [--wait] | get CAPTURE_ID [--site SITE] [--json]";
+export async function runScreenshots(args) {
+    try {
+        const { slug, rest } = await resolveSlug(args), work = [...rest], action = work.shift();
+        const endpoint = `/api/v1/sites/${encodeURIComponent(slug)}/screenshots`;
+        let result;
+        if (action === "capture") {
+            const path = takeFlagValue(work, "--path") ?? "/", device = takeFlagValue(work, "--device") ?? "desktop";
+            const capture = takeFlagValue(work, "--capture") ?? "viewport", selector = takeFlagValue(work, "--selector");
+            const id = takeFlagValue(work, "--request-key") ?? randomUUID(), wait = hasFlag(work, "--wait");
+            assertNoUnknownFlags(work, "screenshots");
+            if (work.length || !["desktop", "mobile"].includes(device) || !["viewport", "full_page", "element"].includes(capture)
+                || (capture === "element") !== !!selector || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id))
+                throw new CliHttpError(usage, EXIT_USAGE, 400);
+            try {
+                result = await v1Post(endpoint, { path, device, capture, ...(selector ? { selector } : {}) }, { idempotencyKey: id, timeoutMs: 30000 });
+            }
+            catch (error) {
+                // The server may already have accepted the request. Give the caller the exact retry key.
+                if (error instanceof Error)
+                    error.message += ` Request key: ${id}. Retry the same input with --request-key ${id}.`;
+                throw error;
+            }
+            if (wait) {
+                const deadline = Date.now() + 180000;
+                while (["queued", "running"].includes(result.status) && Date.now() < deadline) {
+                    await new Promise(resolve => setTimeout(resolve, 2000));
+                    result = await v1Get(`${endpoint}/${result.id}`, { timeoutMs: 15000 });
+                }
+            }
+        }
+        else if (action === "get") {
+            const id = work.shift();
+            assertNoUnknownFlags(work, "screenshots");
+            if (!id || work.length)
+                throw new CliHttpError(usage, EXIT_USAGE, 400);
+            result = await v1Get(`${endpoint}/${encodeURIComponent(id)}`, { timeoutMs: 15000 });
+        }
+        else
+            throw new CliHttpError(usage, EXIT_USAGE, 400);
+        if (isJson())
+            emitOk("screenshots", { slug, ...result });
+        else {
+            console.log(`${result.id}  ${result.status}${result.revision ? `  revision ${result.revision}` : ""}`);
+            if (result.error)
+                console.error(result.error);
+            for (const image of result.result?.images ?? [])
+                console.log(image.url);
+            if (["queued", "running"].includes(result.status))
+                console.log(`Continue: frontpage screenshots get ${result.id} --site ${slug}`);
+        }
+        return result.status === "failed" ? EXIT_USAGE : EXIT_OK;
+    }
+    catch (error) {
+        return emitErr("screenshots", error);
+    }
+}

package/dist/completions/generate.js

@@ -19,6 +19,7 @@ _frontpage_completions() {
     runs) COMPREPLY=( $(compgen -W "list current wait cancel retry get" -- "\${cur}") ) ;;
     deploy) COMPREPLY=( $(compgen -W "wait" -- "\${cur}") ) ;;
     media) COMPREPLY=( $(compgen -W "list upload" -- "\${cur}") ) ;;
+    screenshots) COMPREPLY=( $(compgen -W "capture get --path --device --capture --selector --request-key --wait --site --json" -- "\${cur}") ) ;;
     images) COMPREPLY=( $(compgen -W "generate" -- "\${cur}") ) ;;
     fonts) COMPREPLY=( $(compgen -W "list search" -- "\${cur}") ) ;;
     tokens) COMPREPLY=( $(compgen -W "set" -- "\${cur}") ) ;;
@@ -68,6 +69,7 @@ _frontpage() {
         runs) _values 'subcommand' current wait cancel retry get ;;
         deploy) _values 'subcommand' wait ;;
         media) _values 'subcommand' list upload ;;
+        screenshots) _values 'subcommand' capture get ;;
         images) _values 'subcommand' generate ;;
         fonts) _values 'subcommand' list search ;;
         tokens) _values 'subcommand' set ;;
@@ -109,6 +111,7 @@ export function generateFishCompletion() {
         `complete -c frontpage -n "__fish_seen_subcommand_from runs" -a "current wait cancel retry get"`,
         `complete -c frontpage -n "__fish_seen_subcommand_from deploy" -a "wait"`,
         `complete -c frontpage -n "__fish_seen_subcommand_from media" -a "list upload"`,
+        `complete -c frontpage -n "__fish_seen_subcommand_from screenshots" -a "capture get"`,
         `complete -c frontpage -n "__fish_seen_subcommand_from images" -a "generate"`,
         `complete -c frontpage -n "__fish_seen_subcommand_from fonts" -a "list search"`,
         `complete -c frontpage -n "__fish_seen_subcommand_from tokens" -a "set"`,

package/dist/http/client.d.ts

@@ -40,6 +40,7 @@ export declare function v1Get<T>(path: string, opts?: {
 }): Promise<T>;
 export declare function v1Post<T>(path: string, body?: unknown, opts?: {
     timeoutMs?: number;
+    idempotencyKey?: string;
 }): Promise<T>;
 export declare function v1Put<T>(path: string, body?: unknown): Promise<T>;
 export declare function v1Delete<T>(path: string): Promise<T>;

package/dist/http/client.js

@@ -89,6 +89,8 @@ async function v1Request(method, path, body, opts) {
         Authorization: `Bearer ${key}`,
         Accept: "application/json",
     };
+    if (opts?.idempotencyKey)
+        headers["Idempotency-Key"] = opts.idempotencyKey;
     let payload;
     if (body !== undefined) {
         headers["Content-Type"] = "application/json";

package/dist/registry.js

@@ -3,6 +3,14 @@
  * Only shipped Phase 0–5 commands appear here.
  */
 export const COMMANDS = [
+    {
+        name: "screenshots", summary: "Inspect a rendered site page on desktop or mobile",
+        usage: "frontpage screenshots capture [--path /] [--device desktop|mobile] [--capture viewport|full_page|element] [--selector CSS] [--request-key UUID] [--wait] | get CAPTURE_ID [--site SITE] [--json]",
+        topics: ["site-building", "content"],
+        examples: ["frontpage screenshots capture --path /pricing --device mobile --wait --json", "frontpage screenshots get CAPTURE_ID --json"],
+        flags: ["--request-key UUID preserves the same request after an uncertain response", "--wait polls for up to 180 seconds; a pending result includes its ID", "Image URLs are authenticated API paths; use the same API key to fetch image/png bytes"],
+        dangers: ["Captures built staging pages, not unbuilt edits; check revision and coverage. Results expire after 30 days. Capture does not publish."],
+    },
     {
         name: "help",
         summary: "Show available commands",

package/llms.txt

@@ -69,3 +69,5 @@ Articles needs no setup. Use `frontpage articles create-section --label "Blog" -
 Bookings: read packaged [BOOKING.md](./BOOKING.md) and `frontpage modules booking`. Native commands share workspace validation, per-type forms, resource availability, revisions and stable request keys. Calendar consent and private calendar-link entry use a human handoff; ordinary authorized refresh/hours/connection operations run through shared actions; never pass private feed links or OAuth secrets through CLI/agent inputs.
 
 Analytics reference: https://frontpage.host/developers/analytics. Filter type=pageview for views; count alone includes all matching events. Days presets are 1/7/30/90; bare dashboard defaults to 7, structured ops to 30. SQL dates belong in SQL; parsed reporting allowlists and site RLS apply (4000 chars, 5s, 500 returned rows). Unsafe functions/types, unrelated tables, recursion and unsupported syntax reject. Funnels count session overlap without enforcing chronological order. MCP excludes raw SQL and has its own dashboard/page-detail tools; the CLI has no new page-detail subcommand.
+
+- SCREENSHOTS.md: site-scoped desktop/mobile, full-page and element captures; built revisions, protected images, expiry and request recovery.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "frontpage-host",
-  "version": "0.3.20",
-  "description": "Frontpage CLI — manage your site from the terminal",
+  "version": "0.3.22",
+  "description": "Frontpage CLI \u2014 manage your site from the terminal",
   "type": "module",
   "bin": {
     "frontpage": "dist/bin.js"
@@ -15,7 +15,8 @@
     "MAIL.md",
     "CUSTOMER-INBOX.md",
     "PAYMENTS.md",
-    "BOOKING.md"
+    "BOOKING.md",
+    "SCREENSHOTS.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",