@avocadostudio-ai/site-sdk 0.10.0 → 0.11.1

package/README.md

@@ -133,6 +133,16 @@ export const { GET, POST, OPTIONS } = createEditorApiHandler({
 })
 ```
 
+**A publish may not remove every page.** The route used to validate shape and
+nothing else — `[]` is an array, so a publish that deleted the whole site was
+indistinguishable from one that fixed a heading, and an empty `pages` is
+overwhelmingly a client that failed to load its own state rather than somebody
+deleting nine pages on purpose. Such a publish is refused with `409`; removing
+*some* pages stays an ordinary edit. To empty a site deliberately, send
+`"allowDelete": true` in the body. Set `maxPagesRemoved` if you want a tighter
+bound than "not all of them" — it is measured against your own `getPages`, so
+it applies only when that read succeeds.
+
 ### 5. Add styles
 
 ```tsx
@@ -247,7 +257,7 @@ Your site exposes these endpoints via `createEditorApiHandler`:
 | `/api/editor/draft/disable` | GET | Disable draft mode |
 | `/api/editor/blocks` | GET | Return block manifest (schemas + defaults) |
 | `/api/editor/pages` | GET | Return all published pages |
-| `/api/editor/publish` | POST | Receive pages from editor, persist to CMS |
+| `/api/editor/publish` | POST | Receive pages from editor, persist to CMS. Refuses a publish that removes every page unless the body sets `allowDelete: true`. |
 
 ## Library mode mounts two handlers, not one
 

package/dist/editor-api-handler-core.d.ts

@@ -46,6 +46,16 @@ export interface EditorApiHandlerConfig {
     onPublish?: OnPublishFn;
     /** Secret token required for publish requests. Checked against x-publish-token header. */
     publishSecret?: string;
+    /**
+     * Refuse a publish that removes more than this many pages, unless the body
+     * carries `allowDelete: true`.
+     *
+     * A publish that removes *every* page is refused whatever this is set to —
+     * see `checkDestructivePublish`. This option exists for sites that want a
+     * tighter bound than "not all of them", and it is measured against
+     * `getPages`, so it is only enforceable when that read succeeds.
+     */
+    maxPagesRemoved?: number;
 }
 export interface EditorApiCoreConfig extends EditorApiHandlerConfig {
     /**

package/dist/editor-api-handler-core.js

@@ -36,7 +36,15 @@ export function createEditorApiHandlerCore(config) {
     const blocksHandler = createBlocksHandler(manifestBuilder ? { getManifest: manifestBuilder } : undefined);
     const pagesHandler = createPagesHandler(config.getPages, config.getSiteConfig);
     const publishHandler = config.onPublish
-        ? createPublishHandler(config.onPublish, { publishSecret: config.publishSecret })
+        ? createPublishHandler(config.onPublish, {
+            publishSecret: config.publishSecret,
+            // The same getter `/api/editor/pages` serves, reused as the
+            // destructive-publish baseline. Every route built through this handler
+            // has one, so the guard can count what a publish would remove rather
+            // than only noticing that it removes everything.
+            getPages: config.getPages,
+            maxPagesRemoved: config.maxPagesRemoved
+        })
         : null;
     /*
      * `/api/editor/draft/disable` is two segments, so the fallback cannot simply

package/dist/editor-routes.d.ts

@@ -27,8 +27,82 @@ export declare function createPagesHandler(getPages: () => PageDoc[] | Promise<P
     GET: (request: Request) => Promise<Response>;
     OPTIONS: (request: Request) => Response;
 };
+/**
+ * Why an unconfigured publish endpoint is refused in production rather than
+ * left open.
+ *
+ * `publishSecret` was optional, and every scaffold and example wired it as
+ * `process.env.PUBLISH_TOKEN?.trim() || undefined` — a variable none of them
+ * generated, mentioned in their `.env.local`, or required. So the value was
+ * always `undefined`, `if (secret)` was always false, and `POST
+ * /api/editor/publish` accepted any caller's `pages` array and overwrote the
+ * site's content with it. A deployment that had followed its own README to the
+ * letter, `ACCESS_PASSWORD_HASH` and all, was gated on `/api/avocado/*` and
+ * wide open here: the two route groups are different handlers, and only one of
+ * them had ever been asked about auth.
+ *
+ * An optional guard on a write endpoint is not a guard. This one now fails
+ * closed wherever it matters and says which variable opens it.
+ */
+/**
+ * Why a publish that empties the site is refused.
+ *
+ * The only validation this route ever had was shape: `Array.isArray(body.pages)`.
+ * `[]` is an array, so a publish that removes every page was indistinguishable
+ * from one that fixes a heading. A clean-room run at 0.11.0 sent
+ * `{"pages":[]}` with the token the scaffold itself had generated, under
+ * `NODE_ENV=production`, and got `{"ok":true,"slugs":[]}` back: nine pages
+ * gone, every URL 404, no backup and no confirmation.
+ *
+ * The reason this is a guard rather than a warning is what actually produces an
+ * empty array. It is not somebody deleting their site one page at a time — it
+ * is a client whose state failed to load publishing what it thinks it has.
+ * Losing a site to a failed fetch is not a decision anybody made.
+ *
+ * So the rule is the narrowest one that holds: **a publish may not remove every
+ * page.** Deleting one page is an ordinary edit and stays ordinary; deleting
+ * the last one needs `allowDelete: true` in the body, which is a thing somebody
+ * types on purpose and cannot arrive at by omission. Hosts that want a tighter
+ * bound than "not all of them" set `maxPagesRemoved`.
+ */
+export declare const DESTRUCTIVE_PUBLISH_HINT: string;
+export type PublishGuardResult = {
+    refused: false;
+} | {
+    refused: true;
+    reason: string;
+};
+/**
+ * Decide whether a publish is destructive enough to refuse.
+ *
+ * Exported because it is the whole of the rule, and a rule nobody can test in
+ * isolation is a rule that drifts. `before` is `undefined` when the caller has
+ * no way to read the current state — `createPublishHandler` used directly,
+ * rather than through `createEditorApiHandler`, which always has `getPages`.
+ * Without a baseline an empty publish is still refused: not knowing what is
+ * there is not a reason to overwrite it with nothing.
+ */
+export declare function checkDestructivePublish(args: {
+    next: readonly {
+        slug?: string;
+    }[];
+    before: readonly {
+        slug?: string;
+    }[] | undefined;
+    allowDelete: boolean;
+    maxPagesRemoved?: number;
+}): PublishGuardResult;
+export declare const OPEN_PUBLISH_HINT: string;
 export declare function createPublishHandler(onPublish: OnPublishFn, options?: {
     publishSecret?: string;
+    /**
+     * The currently published pages, used only as the destructive-publish
+     * baseline. `createEditorApiHandler` passes its own `getPages`; a handler
+     * built by hand may omit it and gets the baseline-free rule.
+     */
+    getPages?: () => PageDoc[] | Promise<PageDoc[]>;
+    /** Refuse a publish removing more than this many pages. See `checkDestructivePublish`. */
+    maxPagesRemoved?: number;
 }): {
     POST: (request: Request) => Promise<Response>;
     OPTIONS: (request: Request) => Response;

package/dist/editor-routes.js

@@ -29,12 +29,105 @@ export function createPagesHandler(getPages, getSiteConfig) {
         }
     };
 }
+/**
+ * Why an unconfigured publish endpoint is refused in production rather than
+ * left open.
+ *
+ * `publishSecret` was optional, and every scaffold and example wired it as
+ * `process.env.PUBLISH_TOKEN?.trim() || undefined` — a variable none of them
+ * generated, mentioned in their `.env.local`, or required. So the value was
+ * always `undefined`, `if (secret)` was always false, and `POST
+ * /api/editor/publish` accepted any caller's `pages` array and overwrote the
+ * site's content with it. A deployment that had followed its own README to the
+ * letter, `ACCESS_PASSWORD_HASH` and all, was gated on `/api/avocado/*` and
+ * wide open here: the two route groups are different handlers, and only one of
+ * them had ever been asked about auth.
+ *
+ * An optional guard on a write endpoint is not a guard. This one now fails
+ * closed wherever it matters and says which variable opens it.
+ */
+/**
+ * Why a publish that empties the site is refused.
+ *
+ * The only validation this route ever had was shape: `Array.isArray(body.pages)`.
+ * `[]` is an array, so a publish that removes every page was indistinguishable
+ * from one that fixes a heading. A clean-room run at 0.11.0 sent
+ * `{"pages":[]}` with the token the scaffold itself had generated, under
+ * `NODE_ENV=production`, and got `{"ok":true,"slugs":[]}` back: nine pages
+ * gone, every URL 404, no backup and no confirmation.
+ *
+ * The reason this is a guard rather than a warning is what actually produces an
+ * empty array. It is not somebody deleting their site one page at a time — it
+ * is a client whose state failed to load publishing what it thinks it has.
+ * Losing a site to a failed fetch is not a decision anybody made.
+ *
+ * So the rule is the narrowest one that holds: **a publish may not remove every
+ * page.** Deleting one page is an ordinary edit and stays ordinary; deleting
+ * the last one needs `allowDelete: true` in the body, which is a thing somebody
+ * types on purpose and cannot arrive at by omission. Hosts that want a tighter
+ * bound than "not all of them" set `maxPagesRemoved`.
+ */
+export const DESTRUCTIVE_PUBLISH_HINT = "This publish would remove every page from the site. If that is intended, resend it with " +
+    '`"allowDelete": true` in the body. An empty `pages` array is most often a client that failed ' +
+    "to load its own state, so it is refused by default.";
+/**
+ * Decide whether a publish is destructive enough to refuse.
+ *
+ * Exported because it is the whole of the rule, and a rule nobody can test in
+ * isolation is a rule that drifts. `before` is `undefined` when the caller has
+ * no way to read the current state — `createPublishHandler` used directly,
+ * rather than through `createEditorApiHandler`, which always has `getPages`.
+ * Without a baseline an empty publish is still refused: not knowing what is
+ * there is not a reason to overwrite it with nothing.
+ */
+export function checkDestructivePublish(args) {
+    const { next, before, allowDelete, maxPagesRemoved } = args;
+    if (allowDelete)
+        return { refused: false };
+    if (next.length === 0) {
+        // A site that is already empty cannot be emptied. Publishing nothing onto
+        // nothing is a no-op, and refusing it would fail a brand-new integration on
+        // its very first publish.
+        if (before && before.length === 0)
+            return { refused: false };
+        const had = before ? `${before.length} page${before.length === 1 ? "" : "s"}` : "its pages";
+        return { refused: true, reason: `${DESTRUCTIVE_PUBLISH_HINT} The site currently has ${had}.` };
+    }
+    if (maxPagesRemoved === undefined || !before)
+        return { refused: false };
+    const keeping = new Set(next.map((p) => p.slug));
+    const removed = before.filter((p) => !keeping.has(p.slug));
+    if (removed.length <= maxPagesRemoved)
+        return { refused: false };
+    return {
+        refused: true,
+        reason: `This publish would remove ${removed.length} pages (${removed.map((p) => p.slug).join(", ")}), ` +
+            `and this site is configured to refuse a publish removing more than ${maxPagesRemoved}. ` +
+            'Resend with `"allowDelete": true` if that is intended.'
+    };
+}
+export const OPEN_PUBLISH_HINT = "This publish endpoint overwrites the site's content and has no publishSecret configured, " +
+    "so it refuses every request under NODE_ENV=production. Set PUBLISH_TOKEN (the same value the " +
+    "orchestrator sends as x-publish-token), or pass publishSecret to createEditorApiHandler().";
+let warnedOpenPublish = false;
 export function createPublishHandler(onPublish, options) {
     return {
         OPTIONS: createEditorCorsOptionsHandler(),
         async POST(request) {
             // Verify publish token if configured
             const secret = options?.publishSecret;
+            if (!secret) {
+                if (process.env.NODE_ENV === "production") {
+                    const res = new Response(JSON.stringify({ ok: false, error: "unauthorized", reason: OPEN_PUBLISH_HINT }), { status: 401, headers: { "Content-Type": "application/json" } });
+                    return applyEditorCors(res, request.headers.get("origin"));
+                }
+                // Development: publishing to your own machine is the point, so this
+                // stays open — but it is the same code path that ships, so say so once.
+                if (!warnedOpenPublish) {
+                    warnedOpenPublish = true;
+                    console.warn(`[avocado] ${OPEN_PUBLISH_HINT}`);
+                }
+            }
             if (secret) {
                 const provided = request.headers.get("x-publish-token")?.trim();
                 if (!provided || provided !== secret) {
@@ -49,6 +142,32 @@ export function createPublishHandler(onPublish, options) {
                     return applyEditorCors(res, request.headers.get("origin"));
                 }
                 const pages = body.pages;
+                /*
+                 * The baseline is best-effort on purpose. `getPages` reaches a CMS on
+                 * some integrations, and a publish is not the moment to fail because a
+                 * read timed out — but it is also not the moment to assume the site was
+                 * empty. An unreadable baseline becomes `undefined`, which still
+                 * refuses an empty publish and simply cannot enforce `maxPagesRemoved`.
+                 */
+                let before;
+                if (options?.getPages) {
+                    try {
+                        before = await options.getPages();
+                    }
+                    catch {
+                        before = undefined;
+                    }
+                }
+                const guard = checkDestructivePublish({
+                    next: pages,
+                    before,
+                    allowDelete: body.allowDelete === true,
+                    maxPagesRemoved: options?.maxPagesRemoved
+                });
+                if (guard.refused) {
+                    const res = new Response(JSON.stringify({ ok: false, error: "refused", reason: guard.reason }), { status: 409, headers: { "Content-Type": "application/json" } });
+                    return applyEditorCors(res, request.headers.get("origin"));
+                }
                 const config = (body.siteConfig ?? {});
                 const context = { assets: body.assets };
                 const result = await onPublish(pages, config, context);

package/dist/publish-handlers/json-file.d.ts

@@ -2,6 +2,21 @@ import type { OnPublishFn } from "../editor-routes.ts";
 /**
  * Publish handler that writes PageDoc[] to a local JSON file.
  *
+ * `shape` decides what lands in the file, and it has to match whatever reads
+ * it back. It used to be neither a parameter nor a choice: the handler always
+ * wrote `{ pages, siteConfig }` while this docstring, three of the four call
+ * sites, and `jsonFileAdapter.onPublish` all said `PageDoc[]`. Publishing then
+ * broke the site that had just published — the scaffold's `lib/content.ts`
+ * does `JSON.parse(...) as PageDoc[]` and its `.find` threw on an object, so
+ * every page answered 500, and `examples/sample-site` reads a slug-keyed
+ * object and quietly lost all nine pages. Only `apps/site` survived, because
+ * its reader had already grown a branch for both shapes.
+ *
+ * So: `array` is the default, because it is what the readers and the adapter
+ * expect. Pass `wrapper` when the reader wants `siteConfig` in the same file —
+ * a plain array has nowhere to put it, so site-level settings (name, logo,
+ * nav) are dropped on publish.
+ *
  * When `publicDir` is provided, inline assets (base64 images from the
  * orchestrator) are written to disk and their localhost URLs are rewritten
  * to relative paths in the JSON output.
@@ -21,4 +36,6 @@ import type { OnPublishFn } from "../editor-routes.ts";
 export declare function createJsonFilePublishHandler(filePath: string, options?: {
     publicDir?: string;
     imagePathPrefix?: string;
+    /** `array` writes `PageDoc[]` (default). `wrapper` writes `{ pages, siteConfig }`. */
+    shape?: "array" | "wrapper";
 }): OnPublishFn;

package/dist/publish-handlers/json-file.js

@@ -3,6 +3,21 @@ import { resolve } from "node:path";
 /**
  * Publish handler that writes PageDoc[] to a local JSON file.
  *
+ * `shape` decides what lands in the file, and it has to match whatever reads
+ * it back. It used to be neither a parameter nor a choice: the handler always
+ * wrote `{ pages, siteConfig }` while this docstring, three of the four call
+ * sites, and `jsonFileAdapter.onPublish` all said `PageDoc[]`. Publishing then
+ * broke the site that had just published — the scaffold's `lib/content.ts`
+ * does `JSON.parse(...) as PageDoc[]` and its `.find` threw on an object, so
+ * every page answered 500, and `examples/sample-site` reads a slug-keyed
+ * object and quietly lost all nine pages. Only `apps/site` survived, because
+ * its reader had already grown a branch for both shapes.
+ *
+ * So: `array` is the default, because it is what the readers and the adapter
+ * expect. Pass `wrapper` when the reader wants `siteConfig` in the same file —
+ * a plain array has nowhere to put it, so site-level settings (name, logo,
+ * nav) are dropped on publish.
+ *
  * When `publicDir` is provided, inline assets (base64 images from the
  * orchestrator) are written to disk and their localhost URLs are rewritten
  * to relative paths in the JSON output.
@@ -33,8 +48,8 @@ export function createJsonFilePublishHandler(filePath, options) {
             }
             output = JSON.parse(json);
         }
-        const payload = JSON.stringify({ pages: output, siteConfig: config }, null, 2) + "\n";
-        await writeFile(filePath, payload, "utf8");
+        const body = options?.shape === "wrapper" ? { pages: output, siteConfig: config } : output;
+        await writeFile(filePath, JSON.stringify(body, null, 2) + "\n", "utf8");
         return { ok: true };
     };
 }

package/dist/routes-core.d.ts

@@ -3,7 +3,8 @@ export type { DraftRouteAdapter } from "./draft-routes-core.ts";
 export { createEditorApiHandlerCore } from "./editor-api-handler-core.ts";
 export type { EditorApiHandlerConfig, EditorApiCoreConfig } from "./editor-api-handler-core.ts";
 export { createBlocksHandler, createPagesHandler, createPublishHandler } from "./editor-routes.ts";
-export type { OnPublishFn, InlineAsset, PublishContext } from "./editor-routes.ts";
+export type { OnPublishFn, InlineAsset, PublishContext, PublishGuardResult } from "./editor-routes.ts";
+export { checkDestructivePublish, DESTRUCTIVE_PUBLISH_HINT } from "./editor-routes.ts";
 export { isSafeImageUrl, createImageResolver } from "./publish-utils.ts";
 export type { ImageUploader } from "./publish-utils.ts";
 export { createRevalidateHandler } from "./revalidate-handler.ts";

package/dist/routes-core.js

@@ -13,6 +13,8 @@ export { createDraftEnableHandlerCore, createDraftDisableHandlerCore } from "./d
 export { createEditorApiHandlerCore } from "./editor-api-handler-core.js";
 // Individual editor route handlers — already framework-free.
 export { createBlocksHandler, createPagesHandler, createPublishHandler } from "./editor-routes.js";
+// The destructive-publish rule, and the text of its refusal.
+export { checkDestructivePublish, DESTRUCTIVE_PUBLISH_HINT } from "./editor-routes.js";
 // Publish utilities (SSRF check, image resolution).
 export { isSafeImageUrl, createImageResolver } from "./publish-utils.js";
 // Revalidation handler factory — takes a `revalidate` callback, so the host's

package/dist/routes.d.ts

@@ -1,6 +1,7 @@
 export { createDraftEnableHandler, createDraftDisableHandler } from "./draft-routes.ts";
 export { createBlocksHandler, createPagesHandler, createPublishHandler } from "./editor-routes.ts";
-export type { OnPublishFn, InlineAsset, PublishContext } from "./editor-routes.ts";
+export type { OnPublishFn, InlineAsset, PublishContext, PublishGuardResult } from "./editor-routes.ts";
+export { checkDestructivePublish, DESTRUCTIVE_PUBLISH_HINT } from "./editor-routes.ts";
 export { createEditorApiHandler } from "./editor-api-handler.ts";
 export type { EditorApiHandlerConfig } from "./editor-api-handler.ts";
 export { isSafeImageUrl, createImageResolver } from "./publish-utils.ts";

package/dist/routes.js

@@ -2,6 +2,8 @@
 export { createDraftEnableHandler, createDraftDisableHandler } from "./draft-routes.js";
 // Editor route handler factories
 export { createBlocksHandler, createPagesHandler, createPublishHandler } from "./editor-routes.js";
+// The destructive-publish rule, and the text of its refusal.
+export { checkDestructivePublish, DESTRUCTIVE_PUBLISH_HINT } from "./editor-routes.js";
 // Catch-all editor API handler
 export { createEditorApiHandler } from "./editor-api-handler.js";
 // Publish utilities (SSRF check, image resolution)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/site-sdk",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -147,17 +147,17 @@
   ],
   "dependencies": {
     "zod": "^4.3.6",
-    "@avocadostudio-ai/preview-adapter": "^0.10.0",
-    "@avocadostudio-ai/blocks": "^0.10.0",
-    "@avocadostudio-ai/richtext": "^0.10.0",
-    "@avocadostudio-ai/shared": "^0.10.0"
+    "@avocadostudio-ai/blocks": "^0.11.1",
+    "@avocadostudio-ai/richtext": "^0.11.1",
+    "@avocadostudio-ai/shared": "^0.11.1",
+    "@avocadostudio-ai/preview-adapter": "^0.11.1"
   },
   "peerDependencies": {
     "next": ">=15.0.0",
     "react": ">=19.0.0",
     "react-dom": ">=19.0.0",
     "better-sqlite3": ">=12.0.0",
-    "@avocadostudio-ai/orchestrator-core": "^0.10.0"
+    "@avocadostudio-ai/orchestrator-core": "^0.11.1"
   },
   "peerDependenciesMeta": {
     "@avocadostudio-ai/orchestrator-core": {