frontpage-host 0.3.19 → 0.3.21

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

@@ -54,7 +54,7 @@ A recurring block update/removal adds `--scope this|following|all` and the exact
 
 Calendar consent stays with the person connecting the account. Never put OAuth credentials or private iCal URLs into CLI files, prompts or agent tools. Follow the returned workspace link and connect there. Each member controls their own calendars; admins can connect shared calendars to spaces. Hard refresh permits two distinct attempts per calendar in a rolling 15 minutes, including failures. The same retry identity does not spend another attempt. The dispatcher runs every five minutes; healthy reconciliation targets 15 minutes, plus scheduling delay and provider backoff.
 
-Google and Outlook import busy periods and can receive Frontpage-owned confirmed events when the owner grants write access. Private event details never reach visitors. iCal imports unavailable dates for approval-based stays; it does not send bookings back or provide a real-time double-booking guarantee.
+Google and Outlook import busy periods and can receive Frontpage-owned confirmed events when the owner grants write access. Private event details never reach visitors. iCal imports busy times for appointments or stays under either confirmation policy; it does not send bookings back or provide a real-time double-booking guarantee.
 
 Website authors use the platform Booking runtime and `data-fp-booking` containers. The agent controls surrounding HTML and CSS; the service controls forms, availability, validation, email verification and reservation state. Read the Booking module docs and use their exact starter markup. Do not use the old `data-fp-form="booking"` collector for new forms. Customers review the booking, verify their email and submit; verification creates no inventory hold. A customer management link opens a dedicated page. Viewing a link never accepts, declines or cancels a booking.
 
@@ -66,10 +66,14 @@ All commands above call the same Booking actions as the workspace and internal a
 
 `hours set --file hours.json` takes `{"hours":[{"day":1,"start":"09:00","end":"17:00"}]}` with the current revision/key. The server infers the current user; no target-user flag exists. `activation set --file state.json` takes `{"state":"active"}` (also `disabled` or `archived`). `types save --member-users USER_ID,USER_ID --file type.json` resolves joined members in the shared operation; the complete type value must use `memberResourceIds:[]`. Omit the flag to keep the resource-ID contract. An empty `--member-users ''` clears assigned members.
 
-`connections connect --file setup.json --request-key KEY` takes `{"provider":"google","ownership":"personal"}`. Providers are `google`, `outlook`, `ical`; iCal requires `ownership:"shared"`. Optional `action:"reconnect"` requires the existing `connectionId`. An admin may name `responsibleUserId` to request their joined member's consent; the admin does not receive that member's authorization. Follow the returned workspace URL. The same request appears in the editor status bar and workspace overview. An account-only OAuth return is not complete until calendar selection/binding saves. Failures retain a truthful next step; repeating the same request does not create duplicate notices. `setup dismiss --id REQUEST_ID --revision GENERATION --request-key KEY` hides the request; it does not disconnect or mark connected.
+`connections connect --file setup.json --request-key KEY` takes `{"provider":"google","ownership":"personal"}`. Providers are `google`, `outlook`, `ical`; iCal accepts `ownership:"personal"` for your own member or `ownership:"shared"` for admin-managed spaces. Optional `action:"reconnect"` requires the existing `connectionId`. An admin may name `responsibleUserId` to request their joined member's consent; the admin does not receive that member's authorization. Follow the returned workspace URL. The same request appears in the editor status bar and workspace overview. An account-only OAuth return is not complete until calendar selection/binding saves. Failures retain a truthful next step; repeating the same request does not create duplicate notices. `setup dismiss --id REQUEST_ID --revision GENERATION --request-key KEY` hides the request; it does not disconnect or mark connected.
 
 `accounts calendars --id ACCOUNT_ID` returns owned provider calendar choices. `calendars save --record-kind account --id ACCOUNT_ID --file selection.json --request-key KEY` selects one, using `calendarId`, `label`, `resourceIds`, `receivesBookings` and `ownership`. Editing uses `--record-kind calendar --id CONNECTION_ID --account ACCOUNT_ID --revision N`. Use `--setup REQUEST_ID` when completing a returned connection request. Provider identity and consent remain protected by the server.
 
-`connections save` updates an iCal connection's label/resourceIds with the current revision. `connections refresh --record-kind feed|calendar --id CONNECTION_ID --revision N --request-key KEY` executes the server-limited refresh, not a link-only request. Disconnect uses the same record kind/ID/revision plus `--file disconnect.json` containing `{"confirmed":true,"removeBinding":false}`. `accounts disconnect` uses the account ID/revision and the same explicit value. `removeBinding:false` keeps dependent availability unavailable until reconnected; `true` removes that dependency. Existing bookings remain. Never infer that requesting refresh means sync succeeded.
+`connections save` updates an iCal connection's label/resourceIds with the current revision. `connections refresh --record-kind feed|calendar --id CONNECTION_ID --revision N --request-key KEY` executes the server-limited refresh, not a link-only request. Disconnect uses the same record kind/ID/revision plus `--file disconnect.json` containing `{"confirmed":true,"removeBinding":true}`. `accounts disconnect` uses the account ID/revision and the same explicit value. Normal disconnect uses `true` to stop checking that source. Explicit `removeBinding:false` keeps dependent availability unavailable until reconnected. Existing bookings remain. Never infer that requesting refresh means sync succeeded.
 
 Only consent/private-link entry uses the secure human handoff. Never pass OAuth codes/tokens or private export URLs through files, CLI arguments or chat. `event-open` takes `{"detailId":"OPAQUE_ID_FROM_OWNER_CALENDAR"}`; opening its URL still requires the connecting human. All ordinary reads preserve role redaction; all mutations preserve stable keys, revisions and the existing two-refreshes-per-15-minutes server allowance.
+
+Only the booking type chooses instant confirmation or manual acceptance of customer requests; connecting a calendar never changes that choice. Successful imports revalidate every 15 minutes even when the source advertises a longer cache lifetime. Connection summaries include safe `health` with `status`, `label`, `message` and `usable`. Fresh last-good busy times still apply during refresh or a temporary failure; missing, revoked, disconnected, stale (30 minutes) or uncovered imports keep dependent availability unavailable. Retries keep existing backoff and Retry-After. Imported event titles and private feed URLs never appear in these summaries.
+
+Repeated Connect for your existing Google/Microsoft account returns its current calendar choices without replacing its grant or selections. Use Reconnect on the existing account to renew permissions.

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,6 +1,6 @@
 {
   "name": "frontpage-host",
-  "version": "0.3.19",
+  "version": "0.3.21",
   "description": "Frontpage CLI \u2014 manage your site from the terminal",
   "type": "module",
   "bin": {
@@ -15,7 +15,8 @@
     "MAIL.md",
     "CUSTOMER-INBOX.md",
     "PAYMENTS.md",
-    "BOOKING.md"
+    "BOOKING.md",
+    "SCREENSHOTS.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",