frontpage-host 0.1.15 → 0.1.17

package/dist/registry.js

@@ -104,7 +104,7 @@ export const COMMANDS = [
         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)",
+            "--wait: after push, wait until the new commit's site compile is live (agent-run idle first, then GET /deploy ready)",
         ],
         dangers: [
             "Requires prior pull (baseCommitSha)",
@@ -249,10 +249,16 @@ export const COMMANDS = [
     {
         name: "publish",
         summary: "Promote staging to production",
-        usage: "frontpage publish [--site <slug>] [--json]",
+        usage: "frontpage publish [--site <slug>] [--wait] [--json]",
         topics: ["agent"],
+        examples: ["frontpage publish", "frontpage publish --wait"],
+        flags: [
+            "--wait: wait until the staging tip's site compile is live, then publish (refuses a previous build)",
+            "Prints tip SHA and serving SHA; warns if they differ",
+        ],
         dangers: [
-            "Promotes the current staging tip to PRODUCTION (custom domain)",
+            "Promotes the last ready staging compile to PRODUCTION (custom domain)",
+            "409 if the tip is not compiled yet — wait, then publish",
             "Agents: never run unless the user explicitly asked to publish",
         ],
         seeAlso: ["unpublish", "deploy"],
@@ -270,13 +276,14 @@ export const COMMANDS = [
     },
     {
         name: "deploy",
-        summary: "Wait for an in-flight build to finish (not publish)",
+        summary: "Wait for the current tip's site compile (not publish)",
         usage: "frontpage deploy wait [--site <slug>] [--json]",
         topics: ["agent"],
         flags: [
-            "Optional build wait only — staging is https://<subdomain>.frontpage.host",
+            "Waits for editor-agent idle (if a run is in flight), then until GET /deploy ready",
+            "ready = the live compile SHA equals the git tip — not a historical agent run",
             "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",
+            "Fail-closed: exit 2 when the waited agent run is failed/canceled, or the compile fails or times out",
         ],
     },
     {
@@ -348,7 +355,7 @@ export const COMMANDS = [
         dangers: [
             "Secret values are never returned — masks only",
             "request-setup surfaces an owner prompt in the editor status bar (CLI cannot show it)",
-            "payments and shop share one Stripe account — disconnect warns before teardown",
+            "payments and shop share one Stripe account — payments disconnect 409s if the store still uses it",
             "OAuth cannot finish in the terminal; connect only opens the vendor URL",
             "Do not write placeId through generic config — that skips listing resolve + seed",
         ],
@@ -361,6 +368,24 @@ export const COMMANDS = [
         topics: ["agent", "content"],
         examples: ["frontpage extensions docs charts"],
     },
+    {
+        name: "images",
+        summary: "Generate 1–4 AI image variations of one prompt (counts against AI $ and storage)",
+        usage: 'frontpage images generate --prompt "…" [--count N] [--site <slug>] [--json]',
+        topics: ["content"],
+        examples: [
+            'frontpage images generate --prompt "flat illustration of a red stand mixer on marble"',
+            'frontpage images generate --prompt "watercolor cafe storefront at dusk" --count 4',
+        ],
+        flags: [
+            "One prompt; --count 1–4 is variations of that same picture (default 1)",
+            "Human success: sitePath first (markup-safe), then filename",
+            "Counts against the site AI $ budget and storage; 402 when the cycle is spent",
+            "--count outside 1–4 fails locally (exit 2) with no request",
+            "Unknown leftover flags fail closed (exit 2)",
+        ],
+        seeAlso: ["media", "prompt", "help content", "help site-building"],
+    },
     {
         name: "media",
         summary: "List or upload site media (images/PDF ≤25 MB, video ≤50 MB)",
@@ -478,12 +503,13 @@ export const TOPICS = {
   5. frontpage pull
   6. Edit files under src/, public/, or content/
   7. frontpage push --message "…"
-  8. Review staging: https://<subdomain>.frontpage.host when that subdomain is publicly shareable.
+  8. frontpage deploy wait         # tip compile ready (optional; push --wait does this)
+     Review staging: https://<subdomain>.frontpage.host when that subdomain is publicly shareable.
      With a custom domain connected, the subdomain is often owner-private (login wall ≠ failed push);
      anonymous review is on the published custom domain after publish.
-  9. frontpage publish             # ONLY if the user asked — promotes to production
+  9. frontpage publish [--wait]    # ONLY if the user asked — promotes the ready compile
 
-  Staging is the subdomain. There is no separate staging-deploy step for agents.
+  Push updates the git tip. The site compile is a second clock. deploy wait is not go-live.
   Never publish/unpublish unless the user explicitly asks.
   Agents: read AGENTS.md + frontpage help site-building; use --json for structured I/O.
   More: frontpage help auth | sync | site-building | agent | content | history | isolation | exit-codes`,
@@ -511,7 +537,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).
+  --wait after push blocks until the new commit's site compile is live (agent idle, then GET /deploy ready).
   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.
@@ -520,12 +546,15 @@ export const TOPICS = {
   Do not store secrets in the site tree (.env, *.pem, secrets/, credentials.json) — rejected by the API.
 
   Staging vs production:
-  - Push/prompt/edit update STAGING: https://<subdomain>.frontpage.host
-  - No separate "deploy to staging" step for agents — review the subdomain after the build.
-  - frontpage deploy wait only waits for an in-flight build; it is NOT go-live.
-  - frontpage publish promotes staging → production (custom domain). Never publish unless asked.`,
+  - Push/prompt/edit update the git tip. The site compile is a second clock.
+  - Review STAGING at https://<subdomain>.frontpage.host after GET /deploy is ready.
+  - frontpage deploy wait = agent-run idle (if any) + tip compile ready. It is NOT go-live.
+  - A file-only push has no agent run. deploy wait / push --wait must still wait for the compile.
+  - frontpage publish promotes the last ready staging compile. 409 if the tip is not built yet.
+  - frontpage publish --wait waits for that compile, then publishes. Never publish unless asked.`,
     "site-building": `Site building (Astro contract)
-  Stack: Astro 6 + Tailwind v4. Pages in src/pages/. Every page wraps <BaseLayout title description>.
+  Stack: Astro 6 + Tailwind v4. Pages in src/pages/. Every page wraps <BaseLayout title description>,
+  or a site layout that itself wraps BaseLayout.
   Control files: src/config/tokens.ts (design tokens), src/config/site.ts (title, nav, pages map, seo).
 
   Pages map:
@@ -538,7 +567,10 @@ export const TOPICS = {
   - No API routes, serverless backends, or databases.
   - No fake lead forms / checkout / card fields — use data-fp-* modules + frontpage modules, or refuse.
   - Platform-owned paths are not syncable (BaseLayout overlay, module/extension shells, package.json…).
-  - Customer layouts (DocsLayout, GuideLayout, …) are fine when site-owned.
+  - Customer layouts (DocsLayout, GuideLayout, …) are fine when site-owned. A wrapper MUST render
+    <BaseLayout> and forward SEO: description={description}, ogImage={ogImage}, and
+    title={seoTitle ?? derivedFallback} from a 1:1 Astro.props destructure. NEVER title={pageTitle}
+    with no seoTitle alias (locks Title/Share image in Search & Social for every page on that layout).
 
   Tokens & fonts:
   - Keep required colors/fonts/spacing/radii keys; style via CSS variables / token Tailwind.
@@ -556,7 +588,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: 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.
+  - Media: frontpage media upload (images/PDF ≤25 MB, video ≤50 MB). frontpage images generate --prompt "…" [--count N] for 1–4 AI variations of one invented picture (AI $ + storage). 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`,
@@ -568,8 +600,8 @@ export const TOPICS = {
   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 build wait; fail-closed on failed/canceled; NOT publish
-  frontpage publish              # ONLY if the user asked — production promote
+  frontpage deploy wait          # agent idle + tip compile ready; fail-closed; NOT publish
+  frontpage publish [--wait]     # ONLY if the user asked — promotes the ready compile
   frontpage unpublish --yes      # admin only; never unless asked; --yes when non-TTY
   frontpage usage
   frontpage analytics [--days 7]
@@ -589,6 +621,7 @@ export const TOPICS = {
   Do not publish unless asked.`,
     content: `Content
   frontpage media list|upload <file>   # images/PDF/video; text/CSV = inline not library; sitePath first when stored
+  frontpage images generate --prompt "…" [--count N]  # 1–4 AI variations of one prompt; sitePath first; AI $ + storage
   frontpage inbox [leads|subscribers|orders|google_reviews|…] [--mark-read] [--csv]
   frontpage seo get [/path|--path /path] | seo set --path /
   frontpage articles list|content|create-section|create-article|set-draft|…
@@ -596,7 +629,7 @@ export const TOPICS = {
   frontpage tokens set --group … --key … --value …
   frontpage modules list|docs|request-setup|enable|disable|archive|config <key>
   frontpage modules <key>            # that key's CLI usage
-  frontpage modules payments|shop|ordering connect [--no-open]   # opens Stripe/Square; then status
+  frontpage modules payments|shop|ordering connect [--no-open]   # opens Frontpage then Stripe/Square; then status
   frontpage modules ordering sync
   # mailing list key: signups. Index: https://frontpage.host/developers/modules
   frontpage extensions list|docs|enable|disable|config <key>
@@ -607,7 +640,7 @@ export const TOPICS = {
   Do not fake payments/checkout. LOCKED extensions → do not fake; say plan required.
   Migrate pages → articles: prefer frontpage prompt "migrate …" over mass delete+write.
   edit uses click-edit (exact single occurrence), not push / gated-write.
-  Connect opens Stripe/Square in the browser; this CLI never accepts or returns OAuth secrets.
+  Connect opens Frontpage (logged-in), then Stripe/Square; never accepts or returns OAuth secrets. payments/shop connect is admin.
   Site contract: frontpage help site-building · https://frontpage.host/developers/site-building
   Domains, billing, members, and site delete are out of v1.`,
     history: `History

package/llms.txt

@@ -8,7 +8,7 @@
 - Fonts: frontpage fonts [--slot] [--query] → exact value → tokens set fonts.<role> → APPLY font-sans|serif|mono|display. Build bundles catalog faces from tokens.ts and/or CSS font-family contexts (not prose). Inline-only without tokens works for catalog faces after rebuild; prefer tokens+utilities for brand roles.
 - Module/extension docs: frontpage modules docs <key> | frontpage extensions docs <key>
 - Search flags: --regex --case-sensitive --whole-word --files-only --context-lines --max-results
-- Modules setup: wizard modules (payments/shop/ordering): frontpage modules <key> connect [--no-open] opens Stripe/Square; finish in the browser, then status. request-setup remains valid for the editor amber bar. payments and shop share one Stripe account. frontpage modules <key> prints that key's CLI usage. Index: https://frontpage.host/developers/modules. Typed config: frontpage modules callbar|forms|booking|signups get|set (forms set needs --instance; confirm emails paid-plan only). google_reviews: frontpage modules google_reviews connect --place-id | --maps-url (server resolve + seed; no Autocomplete; do not write placeId via config). Also status, list-reviews, hide/show, set-stars, set-sort, set-weight, reset-weights, refresh, disconnect. Docs: https://frontpage.host/developers/modules/google-reviews. Markup: data-fp-google-reviews / data-fp-google-ask + required data-fp-requires="google_reviews". Ask scores: frontpage inbox google_reviews.
+- Modules setup: wizard modules (payments/shop/ordering): frontpage modules <key> connect [--no-open] opens Frontpage (logged-in browser) then Stripe/Square; already-connected stays live. payments/shop connect = admin key; ordering = editor. payments disconnect 409s if shop still uses the shared Stripe account. request-setup remains valid for the editor amber bar. frontpage modules <key> prints that key's CLI usage. Index: https://frontpage.host/developers/modules. Typed config: frontpage modules callbar|forms|booking|signups get|set (forms set needs --instance; confirm emails paid-plan only). Form destinations: frontpage modules forms destinations|connect-destination|attach-destination|detach-destination|remove-destination --yes|request-destination-setup (token = admin; request-destination-setup lights the editor bar; request-setup forms is a no-op; connect does not attach every form). Privyr: paste Incoming Webhook URL (https://www.privyr.com/api/v1/incoming-leads/…), not a token. HubSpot: Development → Keys → Service keys or Legacy apps → Auth → Show token. Pipedrive: profile → Company settings → Personal preferences → API. Docs: https://frontpage.host/developers/modules#forms-destinations. google_reviews: frontpage modules google_reviews connect --place-id | --maps-url (server resolve + seed; no Autocomplete; do not write placeId via config). Also status, list-reviews, hide/show, set-stars, set-sort, set-weight, reset-weights, refresh, disconnect. Docs: https://frontpage.host/developers/modules/google-reviews. Markup: data-fp-google-reviews / data-fp-google-ask + required data-fp-requires="google_reviews". Ask scores: frontpage inbox google_reviews.
 - Analytics ops: frontpage analytics summary|query|funnel|timeseries|compare|sql (bare analytics = dashboard)
 - Media: frontpage media upload <file> (images/PDF ≤25 MB, video ≤50 MB, SVG/text ≤4 MB); human prints sitePath first — use /__media/uploads/<slug>/… in markup. Text/CSV is inline only (not media library; --json omits full content).
 - Prompt attachments: frontpage prompt "…" --attach <file|/__media/…|https://…> [--asset-url https://…] (same media caps as media upload)
@@ -16,12 +16,12 @@
 - SEO get: frontpage seo get [/path|--path /path]; search path filter: [path|--path <path>]; open [/path|--path /path]
 - Analytics funnel: --steps JSON array or comma paths (/, /pricing); bad JSON → Invalid JSON for --steps
 - Modules: unknown key errors list Known: …; mailing list module key is signups (not subscribe)
-- Errors: --json API envelopes include requestId when the server returned one; local validation omits requestId/httpStatus; runs wait failed/canceled → ok:false + run.error (exit 2); deploy wait fail-closed; push --wait
+- Errors: --json API envelopes include requestId when the server returned one; local validation omits requestId/httpStatus; runs wait failed/canceled → ok:false + run.error (exit 2); deploy wait = agent idle + tip compile ready (fail-closed / compile timeout → exit 2); push --wait and publish --wait wait for GET /deploy ready
 - 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. With a custom domain, subdomain may be owner-private (login wall ≠ failed push); public review is published custom domain.
-- Production: custom domain after frontpage publish — NEVER publish/unpublish unless the user explicitly asks
+- Three clocks: git tip (push/prompt/edit) ≠ site compile (GET /deploy ready) ≠ editor agent run (runs wait). File-only push has no agent run.
+- Production: frontpage publish promotes the last ready compile (409 if tip not built). frontpage publish --wait waits then publishes. NEVER publish/unpublish unless the user explicitly asks. Verify live <meta name="frontpage:commit">.
 - 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 (fail-closed on failed/canceled); it is NOT go-live / publish
+- deploy wait = agent-run idle (if any) + tip compile ready; 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.15",
+  "version": "0.1.17",
   "description": "Frontpage CLI — manage your site from the terminal",
   "type": "module",
   "bin": {