frontpage-host 0.1.1 → 0.1.3

package/AGENTS.md

@@ -17,6 +17,28 @@ frontpage help --json    # introspect commands + topics
 
 Node.js ≥ 20.
 
+## Staging vs production (read this first)
+
+Frontpage has two surfaces:
+
+| Surface | URL | What it is |
+|---------|-----|------------|
+| **Staging** | `https://<subdomain>.frontpage.host` | Working copy for edits, previews, and review |
+| **Production** | Custom domain (when connected), after **publish** | What end customers see on the live domain |
+
+**How changes become visible on staging**
+
+- `frontpage push`, `frontpage prompt`, and `frontpage edit` update the site branch and the **staging** surface.
+- After a push or agent run finishes building, changes are visible at `https://<subdomain>.frontpage.host`.
+- There is **no separate “deploy to staging” step** agents must run. Do not treat `frontpage deploy wait` as “going live.” At most it waits for an in-flight build to finish before you open the subdomain to review.
+- `frontpage open` opens the subdomain staging URL.
+
+**Production publish is a deliberate promote**
+
+- `frontpage publish` copies the current **staging tip** to **production** (custom domain / published site).
+- **Never run `publish` or `unpublish` unless the user explicitly asked**, or the user’s own automation/workflow clearly requires autonomous publishing.
+- Default: finish work on staging, tell the user to review `https://<subdomain>.frontpage.host`, and let **them** publish (or ask you to publish after they approve).
+
 ## Non-interactive auth
 
 ```bash
@@ -32,8 +54,8 @@ frontpage doctor --json
 
 ## Site IDs
 
-- Always use the **subdomain** (`arbiter`, `asimov-press`).
-- Never pass custom domains, FQDNs, or URLs to `use` / `--site`.
+- Always use the **subdomain** (`arbiter`, `asimov-press`) with `use` / `--site`.
+- Never pass custom domains, FQDNs, or URLs as the site id.
 - Folder state: `.frontpage/state.json` → `{ slug, baseCommitSha }`.
 
 ```bash
@@ -44,36 +66,42 @@ frontpage use <subdomain>
 
 ## File sync recipe
 
-Allowlisted roots only: `src/`, `public/`, `content/`. Other paths are never pulled/pushed.
+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
-frontpage deploy wait
-# optional production promote:
-frontpage publish --site <subdomain>
+# Review at https://<subdomain>.frontpage.host
+# Do NOT publish unless the user asked.
 ```
 
 Rules:
 
-1. **Pull before push** so `baseCommitSha` is set (CAS).
-2. **Do not push** while an agent run is active (`status` / `runs`).
-3. Push commits to the site branch and triggers staging deploy. **`publish` promotes staging → production.**
-4. Pushing module markup may auto-activate modules (same as the editor agent).
-5. Binaries use base64; do not UTF-8 round-trip them.
+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`.
 
 ## Agent prompt loop
 
 ```bash
-RUN=$(frontpage prompt "make the hero shorter" --json | …)   # or bare runId on stdout without --json
-frontpage runs wait "$RUN"
-# Mid-task continuation is automatic — there is NO `runs continue` in v1.
-frontpage deploy wait
+frontpage prompt "make the hero shorter"
+frontpage runs wait          # wait for the agent run to finish
+# Review https://<subdomain>.frontpage.host — do not publish unless asked.
 ```
 
+Mid-task continuation is automatic. There is **no** `runs continue` in v1.
+
 ## Content / JSON-native commands
 
 These already return JSON bodies (wrap further with global `--json` where supported):
@@ -81,21 +109,23 @@ These already return JSON bodies (wrap further with global `--json` where suppor
 - `usage`, `analytics`, `seo`, `articles`, `settings`, `inbox` (default JSON)
 - Mutate: `modules enable|disable|archive|config`, `extensions …`
 
-Click-edit (exact single occurrence + deploy), **not** file push:
+Click-edit (exact single occurrence), **not** file push:
 
 ```bash
 frontpage edit --path / --old "exact old" --new "exact new"
 ```
 
+`edit` also updates **staging**, same as push. Still do not publish unless asked.
+
 ## History / revert
 
 ```bash
 frontpage history --json
-frontpage revert <40-char-sha> --yes    # required --yes when non-TTY
+frontpage revert <40-char-sha> --yes    # required --yes when non-TTY; only if user asked
 ```
 
 - `S` = staging tip, `P` = production tip.
-- Revert creates a **new** commit whose tree matches the target (linear restore).
+- Revert creates a **new** commit whose tree matches the target (linear restore) on the site branch (staging).
 - Full 40-char SHA only. Refused while an agent run is active.
 
 ## Exit codes — what to do next
@@ -129,24 +159,33 @@ Failures with `--json` print the envelope on **stdout** (still use the process e
 
 ## Destructive ops — defaults for agents
 
-**Never** run unless the user explicitly asked:
+**Never** run unless the user explicitly asked (or their workflow clearly requires it):
 
+- `frontpage publish` (promotes staging → **production** / custom domain)
 - `frontpage unpublish` (takes production offline) — requires `--yes` when non-TTY
 - `frontpage revert <sha>` — requires `--yes` when non-TTY
 - `frontpage inbox … --mark-read` (side-effecting)
-- Broad `frontpage edit` / settings mutations without a clear request
+- Broad `settings` mutations or mass `edit` without a clear request
 
-`publish` promotes staging to production — confirm intent before running.
+Safe default after finishing work: summarize what changed and give the staging URL for review.
 
-## Out of v1 (do not invent)
+## Other nuances agents often miss
 
-`domains*`, `billing*`, `members*`, `suggestions*`, `sites delete|restore`, `runs continue`, MCP, git remotes / clone URLs.
+1. **CLI site id ≠ public domain.** Target `asimov-press`, not `asimov-press.frontpage.host` or a custom domain.
+2. **Keys are account-wide.** One key can reach every site the user can access.
+3. **404 → exit 4** often means “no access / not found,” not only a bad password.
+4. **Allowlist only.** If a file is not under `src/`, `public/`, or `content/`, the CLI will not sync it. Some scaffold files are platform-owned and refuse CLI read/write.
+5. **Full-tree push for allowlisted roots.** Local allowlisted files become the intended remote tree for those roots on push.
+6. **Active-run guard.** Push/revert refuse while an editor agent run is active (exit 3).
+7. **CAS.** Tip moved since pull → exit 3; pull and retry.
+8. **No invented v1 commands:** `domains*`, `billing*`, `members*`, `suggestions*`, `sites delete|restore`, `runs continue`, MCP, git remotes / clone URLs.
+9. **`deploy wait` ≠ publish.** Optional build wait only; staging visibility is the subdomain.
+10. **Honesty on stubs.** `open --prod` is currently a no-op stub (still opens the subdomain).
 
 ## Isolation (hard fence)
 
 - API never returns another site’s branch, GitHub tokens, or clone URLs.
 - Site targeting is subdomain → `site/<slug>` only.
-- Non-member site calls → 404 (exit 4) — do not treat as “wrong password” only.
 - See `frontpage help isolation`.
 
 ## Canonical introspection
@@ -155,5 +194,6 @@ Failures with `--json` print the envelope on **stdout** (still use the process e
 frontpage help
 frontpage help --json
 frontpage help sync
+frontpage help agent
 frontpage doctor --json
 ```

package/README.md

@@ -24,7 +24,8 @@ Requires Node.js ≥ 20.
 4. `mkdir my-site && cd my-site && frontpage use <subdomain>`
 5. `frontpage pull` → edit files under `src/`, `public/`, or `content/`
 6. `frontpage push --message "describe the change"`
-7. `frontpage deploy wait` (staging). Optional: `frontpage publish` (production).
+7. Review staging at `https://<subdomain>.frontpage.host` (no separate staging-deploy step).
+8. `frontpage publish` only when you intentionally promote to production.
 
 ## Environment
 

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/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.js

@@ -86,11 +86,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",
@@ -153,7 +156,10 @@ export const COMMANDS = [
         summary: "Promote staging to production",
         usage: "frontpage publish [--site <slug>] [--json]",
         topics: ["agent"],
-        dangers: ["Promotes the current staging tip to production"],
+        dangers: [
+            "Promotes the current staging tip to PRODUCTION (custom domain)",
+            "Agents: never run unless the user explicitly asked to publish",
+        ],
         seeAlso: ["unpublish", "deploy"],
     },
     {
@@ -161,13 +167,21 @@ export const COMMANDS = [
         summary: "Take the live site offline (admin)",
         usage: "frontpage unpublish [--site <slug>] [--yes] [--json]",
         topics: ["agent"],
-        dangers: ["Takes production offline", "Requires --yes when stdin is not a TTY"],
+        dangers: [
+            "Takes production offline",
+            "Requires --yes when stdin is not a TTY",
+            "Agents: never run unless the user explicitly asked",
+        ],
     },
     {
         name: "deploy",
-        summary: "Wait for active agent deploy to finish",
+        summary: "Wait for an in-flight build to finish (not publish)",
         usage: "frontpage deploy wait [--site <slug>] [--json]",
         topics: ["agent"],
+        flags: [
+            "Optional build wait only — staging is https://<subdomain>.frontpage.host",
+            "Does NOT promote to production; use publish only when the user asks",
+        ],
     },
     {
         name: "usage",
@@ -296,9 +310,11 @@ export const TOPICS = {
   5. frontpage pull
   6. Edit files under src/, public/, or content/
   7. frontpage push --message "…"
-  8. frontpage deploy wait         # staging
-  9. frontpage publish             # optional: promote to production
+  8. Review https://<subdomain>.frontpage.host  (staging)
+  9. frontpage publish             # ONLY if the user asked — promotes to production
 
+  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`,
     auth: `Authentication
@@ -313,31 +329,39 @@ 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).
-  Push updates staging; use frontpage publish to promote production.`,
+  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.`,
     agent: `Agent + publish
   frontpage prompt "make the hero shorter"
   frontpage runs                 # latest + active
   frontpage runs wait [runId]
   frontpage runs cancel <runId>
   frontpage runs retry <runId>
-  frontpage deploy wait
-  frontpage publish
-  frontpage unpublish --yes      # admin only; --yes required when non-TTY
+  frontpage deploy wait          # optional: wait for build; 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
   frontpage analytics [--days 7]
   frontpage pages
@@ -345,7 +369,8 @@ export const TOPICS = {
   frontpage extensions
 
   Mid-task continuation is automatic — there is no runs continue.
-  Do not push while an agent run is active.`,
+  Do not push while an agent run is active.
+  Default after work: review https://<subdomain>.frontpage.host; do not publish.`,
     content: `Content
   frontpage media list|upload <file>
   frontpage inbox [leads|subscribers|orders|…] [--mark-read] [--csv]

package/llms.txt

@@ -6,7 +6,9 @@
 - Topics: quickstart, auth, sync, agent, content, history, isolation, exit-codes
 - 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.
-- Sync: allowlist src/ public/ content/; pull → edit → push (CAS baseCommitSha); no push during active agent run
-- Staging after push/prompt; frontpage publish promotes to production
+- 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
 - 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.1",
+  "version": "0.1.3",
   "description": "Frontpage CLI — manage your site from the terminal",
   "type": "module",
   "bin": {