frontpage-host 0.1.2 → 0.1.4

package/AGENTS.md

@@ -66,12 +66,15 @@ frontpage use <subdomain>
 
 ## File sync recipe
 
-Allowlisted roots only: `src/`, `public/`, `content/`. Other paths never sync (including some platform-owned scaffold files).
+Allowlisted roots only: `src/`, `public/`, `content/`. Other paths never sync (including platform-owned scaffold/overlay files such as `BaseLayout.astro`, `Modules.astro`, and `src/components/extensions/**`). Do not store secrets in the site tree (`.env`, `*.pem`, `secrets/`, `credentials.json`) — the API rejects those paths.
 
 ```bash
+# Session start / before editing: refresh if tip may have moved
+frontpage status --json        # data.tipDrift === true → must pull
+# or just:
 frontpage pull
 # edit local allowlisted files
-frontpage diff --json          # data.dirty === true when local ≠ remote
+frontpage diff --json          # data.dirty / data.tipDrift; compares git blob SHAs (one list GET)
 frontpage push --message "…"
 # on exit 3 (CAS / active run): frontpage status --json → pull or wait → retry push
 # Review at https://<subdomain>.frontpage.host
@@ -80,12 +83,35 @@ frontpage push --message "…"
 
 Rules:
 
-1. **Pull before push** so `baseCommitSha` is set (CAS).
-2. **Do not push** while an agent run is active (`status` / `runs`).
-3. Push updates **staging** (subdomain). Production is unchanged until someone runs `publish`.
-4. Pushing module markup may auto-activate modules (same as the editor agent).
-5. Binaries use base64; do not UTF-8 round-trip them.
-6. Prefer reviewing the subdomain after push; only use `deploy wait` if you need to block until a build finishes.
+1. **Pull before edit** when the remote tip may have moved (UI agent, another machine, or you pushed elsewhere). Check `status --json` / `diff --json` → `tipDrift`, or pull at session start. Stale local trees are not auto-healed; CAS only blocks a bad **push**.
+2. **Pull before push** so `baseCommitSha` is set (CAS). Still required even if you already pulled to edit.
+3. **Do not push** while an agent run is active (`status` / `runs`).
+4. Push updates **staging** (subdomain). Production is unchanged until someone runs `publish`.
+5. Pushing module markup may auto-activate modules (same as the editor agent).
+6. Binaries use base64; do not UTF-8 round-trip them.
+7. Prefer reviewing the subdomain after push; only use `deploy wait` if you need to block until a build finishes.
+8. The **UI / canvas agent does not use this CLI** — it edits the live tip in-process. Only CLI checkouts need `pull`.
+
+## Site contract (Astro)
+
+Sites are Astro 6 + Tailwind v4. More detail: `frontpage help site-building` or https://frontpage.host/developers/site-building
+
+1. **Every page** wraps content in `<BaseLayout title="…" description="…">` (import from `src/layouts/BaseLayout.astro`).
+2. **`src/config/site.ts`** — keep `pages` (path registry) and `nav` in sync when adding/renaming/deleting page files. Tab title comes from BaseLayout, not the `pages` map label.
+3. **One file per URL** for similar page sets (services, guides, …). Do not default to `getStaticPaths()` over `src/data/*.ts`. Blog/news → `frontpage articles`, not a hand-rolled catalog.
+4. **No backends / databases / fake forms or checkout.** Real forms use `<form data-fp-form="slug">` + `frontpage modules`. Refuse or use modules for payments.
+5. **Tokens** in `src/config/tokens.ts` — keep required color/font/spacing/radii keys; style via CSS variables / token Tailwind. Setting a font token is not enough — apply `font-sans` / `font-serif` / `font-display`. No CLI font catalog yet; use existing tokens or `frontpage prompt`.
+6. **Shared chrome** — prefer `src/components/Header.astro` + `Footer.astro` (or `chrome: { managed: true }` in `site.ts`).
+7. **404** — customize `src/pages/404.astro` if needed; keep `frontpage:404` meta; never register `/404` in `nav`/`pages`.
+8. **Platform-owned paths** stay off-limits (BaseLayout overlay, module/extension shells, `package.json`, …). Customer layouts like `DocsLayout` / `GuideLayout` are OK.
+
+## Modules & articles
+
+- Forms: `data-fp-form` markup in pages + `frontpage modules` for enable/config. No submit JS / honeypot / `action`.
+- Articles: `frontpage articles …` for lifecycle; bodies via sync under `content/` or `articles content get|set`. Section landing is an owned `src/pages/<section>/index.astro`.
+- Migrate a folder into Articles: prefer `frontpage prompt "migrate … into articles"` — do not invent a mass delete+write migration.
+- Extensions: `frontpage extensions`; if LOCKED on plan, do not fake charts/etc.
+- Media in markup: `/__media/uploads/<slug>/…` from `frontpage media` (not raw blob URLs).
 
 ## Agent prompt loop
 
@@ -189,6 +215,7 @@ Safe default after finishing work: summarize what changed and give the staging U
 frontpage help
 frontpage help --json
 frontpage help sync
+frontpage help site-building
 frontpage help agent
 frontpage doctor --json
 ```

package/dist/commands/diff.js

@@ -1,9 +1,10 @@
-import { readFile, readdir, stat } from "node:fs/promises";
-import { createHash } from "node:crypto";
+import { readFile, readdir } from "node:fs/promises";
 import { join, relative, sep } from "node:path";
 import { resolveSlug } from "../site.js";
 import { EXIT_OK, EXIT_USAGE, v1Get } from "../http/client.js";
 import { emitErr, emitOk, emitUsage, isJson } from "../runtime.js";
+import { readState } from "../state/frontpage-state.js";
+import { gitBlobSha, isGitBlobSha } from "../git-blob-sha.js";
 const ROOTS = ["src", "public", "content"];
 async function walkLocal(cwd) {
     const map = new Map();
@@ -27,7 +28,7 @@ async function walkLocal(cwd) {
                 if (!ROOTS.some((r) => rel === r || rel.startsWith(`${r}/`)))
                     continue;
                 const buf = await readFile(child);
-                map.set(rel, createHash("sha256").update(buf).digest("hex"));
+                map.set(rel, gitBlobSha(buf));
             }
         }
     }
@@ -35,32 +36,32 @@ async function walkLocal(cwd) {
         await walk(join(cwd, root));
     return map;
 }
-function remoteHash(file) {
-    const buf = file.encoding === "base64"
-        ? Buffer.from(file.content, "base64")
-        : Buffer.from(file.content, "utf8");
-    return createHash("sha256").update(buf).digest("hex");
+function assertRemoteBlobShas(files) {
+    for (const f of files) {
+        if (!isGitBlobSha(f.blobSha)) {
+            throw new Error("Remote file list is missing blobSha. Upgrade Frontpage (API) — this CLI requires git blob SHAs on GET /files and will not fall back to per-file downloads.");
+        }
+    }
 }
 export async function runDiff(args) {
     try {
         const { slug } = await resolveSlug(args);
         const cwd = process.cwd();
+        const state = await readState(cwd);
         const local = await walkLocal(cwd);
         const listing = await v1Get(`/api/v1/sites/${encodeURIComponent(slug)}/files`);
-        const remotePaths = new Set(listing.files.map((f) => f.path));
+        assertRemoteBlobShas(listing.files);
+        const remoteByPath = new Map(listing.files.map((f) => [f.path, f.blobSha]));
         const added = [];
         const modified = [];
         const deleted = [];
         for (const path of [...local.keys()].sort()) {
-            if (!remotePaths.has(path)) {
+            const remoteSha = remoteByPath.get(path);
+            if (!remoteSha) {
                 added.push(path);
                 continue;
             }
-            const encPath = path.split("/").map(encodeURIComponent).join("/");
-            const remote = await v1Get(`/api/v1/sites/${encodeURIComponent(slug)}/files/${encPath}`);
-            const rh = remoteHash(remote.file);
-            const lh = local.get(path);
-            if (rh !== lh)
+            if (remoteSha.toLowerCase() !== local.get(path).toLowerCase())
                 modified.push(path);
         }
         for (const f of listing.files) {
@@ -68,12 +69,16 @@ export async function runDiff(args) {
                 deleted.push(f.path);
         }
         const dirty = added.length + modified.length + deleted.length > 0;
-        void (await stat(cwd).catch(() => null));
+        const tipDrift = Boolean(state.baseCommitSha &&
+            listing.baseCommitSha &&
+            state.baseCommitSha !== listing.baseCommitSha);
         if (isJson()) {
             emitOk("diff", {
                 slug,
                 baseCommitSha: listing.baseCommitSha,
                 dirty,
+                tipDrift,
+                comparedWith: "blobSha",
                 added,
                 modified,
                 deleted,
@@ -92,6 +97,9 @@ export async function runDiff(args) {
         else {
             console.error(`# ${added.length + modified.length + deleted.length} difference(s) · tip ${(listing.baseCommitSha ?? "").slice(0, 7) || "?"} · A=local-only M=modified D=remote-only`);
         }
+        if (tipDrift) {
+            console.error("# tipDrift: remote tip moved since last pull — run frontpage pull before editing further");
+        }
         return EXIT_OK;
     }
     catch (err) {

package/dist/completions/generate.js

@@ -14,7 +14,7 @@ _frontpage_completions() {
   fi
   local cmd="\${COMP_WORDS[1]}"
   case "\${cmd}" in
-    help) COMPREPLY=( $(compgen -W "\${cmds} quickstart auth sync agent content history isolation exit-codes" -- "\${cur}") ) ;;
+    help) COMPREPLY=( $(compgen -W "\${cmds} quickstart auth sync site-building agent content history isolation exit-codes" -- "\${cur}") ) ;;
     completion) COMPREPLY=( $(compgen -W "bash zsh fish" -- "\${cur}") ) ;;
     runs) COMPREPLY=( $(compgen -W "list current wait cancel retry get" -- "\${cur}") ) ;;
     deploy) COMPREPLY=( $(compgen -W "wait" -- "\${cur}") ) ;;

package/dist/git-blob-sha.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Git blob object SHA-1 — same digest as `git hash-object` / GitHub tree `sha`.
+ * Header is `blob <byteLength>\0` followed by raw file bytes (not UTF-8 reinterpreted).
+ */
+export declare function gitBlobSha(content: Buffer): string;
+/** True when a remote list entry carries a usable git blob SHA. */
+export declare function isGitBlobSha(value: unknown): value is string;

package/dist/git-blob-sha.js

@@ -0,0 +1,14 @@
+import { createHash } from "node:crypto";
+/**
+ * Git blob object SHA-1 — same digest as `git hash-object` / GitHub tree `sha`.
+ * Header is `blob <byteLength>\0` followed by raw file bytes (not UTF-8 reinterpreted).
+ */
+export function gitBlobSha(content) {
+    const header = Buffer.from(`blob ${content.length}\0`, "utf8");
+    return createHash("sha1").update(header).update(content).digest("hex");
+}
+const BLOB_SHA_RE = /^[0-9a-f]{40}$/i;
+/** True when a remote list entry carries a usable git blob SHA. */
+export function isGitBlobSha(value) {
+    return typeof value === "string" && BLOB_SHA_RE.test(value);
+}

package/dist/registry.d.ts

@@ -14,6 +14,6 @@ export type CommandDef = {
     seeAlso?: string[];
 };
 export declare const COMMANDS: readonly CommandDef[];
-export declare const TOPIC_NAMES: readonly ["quickstart", "auth", "sync", "agent", "content", "history", "isolation", "exit-codes"];
+export declare const TOPIC_NAMES: readonly ["quickstart", "auth", "sync", "site-building", "agent", "content", "history", "isolation", "exit-codes"];
 export declare const TOPICS: Record<string, string>;
 export declare function findCommand(name: string): CommandDef | undefined;

package/dist/registry.js

@@ -7,8 +7,24 @@ export const COMMANDS = [
         name: "help",
         summary: "Show available commands",
         usage: "frontpage help [command|topic] [--json]",
-        topics: ["auth", "sync", "agent", "content", "history", "isolation", "exit-codes", "quickstart"],
-        examples: ["frontpage help", "frontpage help sync", "frontpage help push", "frontpage help --json"],
+        topics: [
+            "auth",
+            "sync",
+            "site-building",
+            "agent",
+            "content",
+            "history",
+            "isolation",
+            "exit-codes",
+            "quickstart",
+        ],
+        examples: [
+            "frontpage help",
+            "frontpage help sync",
+            "frontpage help site-building",
+            "frontpage help push",
+            "frontpage help --json",
+        ],
     },
     {
         name: "login",
@@ -86,11 +102,14 @@ export const COMMANDS = [
     },
     {
         name: "diff",
-        summary: "Compare local allowlisted files to the remote tip",
+        summary: "Compare local allowlisted files to the remote tip (git blob SHA)",
         usage: "frontpage diff [--site <slug>] [--json]",
         topics: ["sync"],
         examples: ["frontpage diff --json"],
-        flags: ["--site <slug>", "JSON data.dirty is true when differences exist"],
+        flags: [
+            "--site <slug>",
+            "JSON data.dirty when local ≠ remote; data.tipDrift when last pull tip ≠ remote tip",
+        ],
     },
     {
         name: "ls",
@@ -288,6 +307,7 @@ export const TOPIC_NAMES = [
     "quickstart",
     "auth",
     "sync",
+    "site-building",
     "agent",
     "content",
     "history",
@@ -312,8 +332,8 @@ export const TOPICS = {
 
   Staging is the subdomain. There is no separate staging-deploy step for agents.
   Never publish/unpublish unless the user explicitly asks.
-  Agents: read AGENTS.md in the npm package; use --json for structured I/O.
-  More: frontpage help auth | sync | agent | content | history | isolation | exit-codes`,
+  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`,
     auth: `Authentication
   1. Create a key in the Frontpage editor: profile menu → Developers
   2. frontpage login
@@ -326,27 +346,63 @@ export const TOPICS = {
   PUBLIC_CLI_ENABLED is server-side — the CLI cannot enable it.`,
     sync: `File sync
   frontpage use <subdomain>
+  frontpage status               # tipDrift when remote moved since last pull
   frontpage pull                 # downloads src/, public/, content/ into cwd
-  frontpage diff                 # local vs remote tip (--json → data.dirty)
+  frontpage diff                 # local vs remote via git blobSha (--json → dirty + tipDrift)
   frontpage push [--message …]   # uploads allowlisted files; CAS + active-run guard
   frontpage ls [prefix]
   frontpage cat <path>
   frontpage search <pattern>
-  frontpage status
   frontpage open                 # opens https://<slug>.frontpage.host/ (--prod is a no-op stub)
 
   Local state: .frontpage/state.json { slug, baseCommitSha }
-  Pull first so push can compare-and-swap on baseCommitSha.
-  Do not push while the editor agent is building (status / runs show active work).
+  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.
+  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.
   Binaries use base64 (not utf8-corrupted).
+  Platform overlay files (BaseLayout, Modules, Analytics, extensions, …) are not syncable.
+  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.`,
+    "site-building": `Site building (Astro contract)
+  Stack: Astro 6 + Tailwind v4. Pages in src/pages/. Every page wraps <BaseLayout title description>.
+  Control files: src/config/tokens.ts (design tokens), src/config/site.ts (title, nav, pages map, seo).
+
+  Pages map:
+  - Add/rename/delete a page file ⇒ update pages (+ nav if needed) in the SAME change set.
+  - Real title/description live on <BaseLayout>, not as authority in the pages map.
+  - One discrete .astro file per URL for similar sets (services, guides…). Do NOT default to
+    getStaticPaths() over src/data/*.ts. Blog/news → frontpage articles.
+
+  Hard fences:
+  - 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.
+
+  Tokens & fonts:
+  - Keep required colors/fonts/spacing/radii keys; style via CSS variables / token Tailwind.
+  - Setting fonts.sans is not enough — apply font-sans / font-serif / font-display on elements.
+  - No frontpage fonts catalog command yet; read tokens.ts or frontpage prompt.
+
+  Chrome / SEO / 404:
+  - Prefer src/components/Header.astro + Footer.astro (or chrome: { managed: true } in site.ts).
+  - seo block in site.ts + frontpage seo get|set; customize 404.astro but keep frontpage:404 meta;
+    never put /404 in nav or pages. robots/sitemap are platform-managed.
+
+  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).
+
+  Full guide: https://frontpage.host/developers/site-building
+  See also: frontpage help sync | content | AGENTS.md`,
     agent: `Agent + publish
   frontpage prompt "make the hero shorter"
   frontpage runs                 # latest + active
@@ -375,8 +431,12 @@ export const TOPICS = {
   frontpage settings get|set
   frontpage edit --path / --old "…" --new "…"
 
+  Real forms (file sync): <form data-fp-form="slug"> + named inputs — no action/onsubmit/honeypot.
+  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.
   Module OAuth and secret values are not exposed via the CLI.
+  Site contract: frontpage help site-building · https://frontpage.host/developers/site-building
   Domains, billing, members, and site delete are out of v1.`,
     history: `History
   frontpage history [--limit 20] [--page 1]

package/llms.txt

@@ -3,12 +3,13 @@
 - Package: frontpage-host (npm). Binary: frontpage. Do NOT install npm package "frontpage".
 - Docs in this package: README.md, AGENTS.md (agent operating manual).
 - Introspect: frontpage help | frontpage help --json | frontpage help <topic|command>
-- Topics: quickstart, auth, sync, agent, content, history, isolation, exit-codes
+- Topics: quickstart, auth, sync, site-building, agent, content, history, isolation, exit-codes
+- Site building: frontpage help site-building — Astro pages map, BaseLayout, tokens, no backends/fake forms
 - 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/; pull → edit → push (CAS); no push during active agent run; 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 (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
 - 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.2",
+  "version": "0.1.4",
   "description": "Frontpage CLI — manage your site from the terminal",
   "type": "module",
   "bin": {